SpatialPosters

Next-Generation Dynamic Poster Studio & Stremio Artwork Engine

Created by @TheAceOfficials

---

📖 Overview

SpatialPosters is an advanced, ultra-high-performance artwork engine and dynamic poster generator built for Stremio, Jellyfin, Plex, Emby, and cinephiles worldwide.

It transforms ordinary poster thumbnails into stunning, studio-grade cinematic artwork in real-time. By compositing textless high-resolution posters with vector title logos, multi-provider rating badges, 4K streaming quality indicators, award ribbons, and computer-vision focal placement, SpatialPosters delivers a native, state-of-the-art media experience across all your devices.

---

📱 Application Interface Showcase

Explore the intuitive, liquid-glass visual interface designed for effortless poster customization and catalog management.

✨ 3D Poster Deck & Collection Showcase — Interactive Apple TV & Netflix-style 3D poster decks for previewing saved media items.

📚 My Posters Library & Catalog Manager — Organise your saved poster collection, manage custom catalogs, and browse media items in high resolution.

🎨 WYSIWYG Live Poster Studio Workspace — Live 3-Column desktop workspace featuring vector title logo selection, real-time preview, badge styling, and fine-tuning controls.

---

🖼️ Poster Output Showcase

Here are actual real-time poster compositions generated on demand by the SpatialPosters Sharp C++ vector engine:

✨ Key Composition Features: Pristine textless graphics • Vector studio logos • Multi-provider ratings • 4K streaming indicators • Award ribbons • Auto accent color detection

---

🔥 Key Features & Capabilities

🔄 24-Hour Auto-Rotation Dynamic Posters

• Daily Refresh Engine: Automatically cycles clean alternative artwork for movies and TV series every 24 hours, ensuring your media library stays fresh and dynamic.
• Deterministic Seed Selection: Ensures smooth, consistent rotation across devices without duplicate image flashes.

🎨 Auto-Detect Accent & Top Edge Colors

• Pixel Color Analyzer: Analyzes poster image pixels using HTML5 Canvas & C++ color extraction algorithms.
• Dynamic Theme Integration: Automatically computes the dominant accent color and top edge tint to colorize badge styles, bottom gradients, and ambient UI lighting.

🏷️ 6 Customizable Badge Styles

• Liquid Glass (vetro): Glossy backdrop-blur glassmorphic pill badge with subtle inner highlights.
• Bordered (bordo): Sleek dark card container with delicate border accents.
• Bar (bar): Top horizontal accent bar styling.
• Pill (pill): Ultra-clean rounded capsule badge.
• Shadow (shadow): Deep ambient dark glow backdrop.
• Colored (colored): Vibrant solid/gradient background matching the poster's dominant color palette.

🌟 4K Quality & Audio Indicators

• Streaming Quality Badges: Live indicators for 4K UHD, 1080p Full HD, 720p, HDR10+, Dolby Vision, Dolby Atmos, DTS-X, and IMAX Enhanced.
• Automatic Quality Matching: Dynamically attaches media specs directly onto poster artwork.

⭐ Multi-Provider Ratings & Top 10 Ribbons

• Aggregated Scores: Combines live scores from IMDb, TMDB, MDBList, Rotten Tomatoes, Letterboxd, MyAnimeList, and Simkl.
• Prestige Award Badges: Oscar Winner, Cannes Palme d'Or, Emmy, and BAFTA award indicators.
• Vertical Top 10 Ribbons: Official vertical ranking ribbons for Netflix Top 10, Prime Video, Disney+, Apple TV+, HBO Max, and FlixPatrol.

🎬 Vector Studio Logos & Computer-Vision Auto-Fit

• 10,000+ Vector Logos: Access crystal-clear SVG logos for major studios and networks.
• Focal Area Detection: Smart computer-vision algorithms analyze focal zones (such as actors' faces) to automatically position and scale title logos without obscuring key visual elements.

🌐 Universal Custom Poster URL Import

• Limitless Artwork Sourcing: Easily import custom poster artwork from Pinterest, Reddit, ThePosterDB (TPDB), Imgur, or any direct web image link.
• Instant Studio Compositing: Paste any custom poster URL directly into the studio workspace—SpatialPosters instantly applies vector logos, 4K resolution badges, and rating overlays onto your custom artwork in real-time.

📺 Smart Season & Anime Unpacker

• Multi-Part Series Detection: Automatically groups multi-part series (e.g. Money Heist, Lupin) into their intended watch order.
• Anime Mega-Season Unpacker: Unpacks collapsed TMDB mega-seasons (e.g. Jujutsu Kaisen, Re:ZERO) into distinct seasonal story arcs.

🌐 Reddit Community Posters (r/SpatialPosters)

• Real-time Subreddit Syncing: SpatialPosters features a zero-setup, direct integration with the r/SpatialPosters Reddit community.
• Crowdsourced Excellence: Users can discover and instantly apply community-made cinematic posters uploaded on Reddit right within the SpatialPosters Live Studio Workspace, making it the ultimate hub for high-quality crowdsourced artwork.

⚡ Multi-Cloud Storage & High-Speed Caching

• Cloudinary Storage Provider: Instant 25GB free tier hosting with automatic WebP/AVIF format optimization and direct CDN URL generation.
• ImgBB Hosting: 100% free image hosting integration with zero credit card requirements.
• Cloudflare R2: 10GB free tier S3-compatible persistent storage cache, reducing server CPU usage on Vercel by up to 95%.
• Upstash Redis KV: Ultra-fast key-value cache for poster mappings and configuration tokens.

---

🛠️ Setup & Installation Guide

Prerequisites

• Node.js: v18.0.0 or higher (v20+ recommended)
• npm / pnpm / yarn
• TMDB API Key (v3): Get a free key from themoviedb.org/settings/api

---

💻 Local Development Setup

1. Clone the repository:

   git clone https://github.com/TheAceOfficials/SpatialPosters.git
   cd SpatialPosters

2. Install dependencies:

   npm install

3. Configure environment variables:

   cp .env.example .env.local

   Open .env.local and enter your TMDB API key:

   SPATIALPOSTERS_TMDB_KEY=your_tmdb_v3_api_key
   SPATIALPOSTERS_PUBLIC_INSTANCE=1

4. Start the development server:

   npm run dev

   Open http://localhost:3000 in your browser.

---

🐳 Docker & Docker Compose Setup

Run SpatialPosters as a lightweight, isolated container using Docker:

Using Docker Compose (Recommended)

docker compose up -d

Using Docker CLI

docker run -d \
  --name spatialposters \
  -p 3000:3000 \
  -e SPATIALPOSTERS_TMDB_KEY="your_tmdb_v3_api_key" \
  -e SPATIALPOSTERS_PUBLIC_INSTANCE=1 \
  -v spatialposters_data:/data \
  --restart unless-stopped \
  theaceofficials/spatialposters:latest

---

☁️ 1-Click Cloud Deployment

Deploy to Vercel (Best Free Recommended Setup)

1. Click the Deploy with Vercel button above or import your repository on vercel.com.
2. Connect Upstash Redis storage via Vercel Integrations (Free Tier) for lightning-fast configuration caching.
3. Add the following 100% Free Optimized Environment Variables:
   • SPATIALPOSTERS_TMDB_KEY = your TMDB v3 API key
   • SPATIALPOSTERS_PUBLIC_INSTANCE = 1
   • CLOUDINARY_CLOUD_NAME = your Cloudinary Cloud Name (Free 25GB Tier)
   • CLOUDINARY_API_KEY = your Cloudinary API Key
   • CLOUDINARY_API_SECRET = your Cloudinary API Secret

Deploy to Render / HuggingFace Spaces

Deploy using the included Dockerfile on any Docker-compatible hosting platform.

---

⚙️ Environment Variables Reference

Below is the complete reference of environment variables supported by SpatialPosters:

🌟 Recommended Cloud Storage Setup

Tip

Cloudinary vs ImgBB Recommendation: We strongly recommend setting up Cloudinary (CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET).

• Why Cloudinary?: Offers a generous 25GB free tier, automatic WebP/AVIF next-gen format compression, instant global CDN delivery, and reduces Vercel CPU execution time to zero for cached posters.
• ImgBB: Ideal as a 100% free alternative with no credit card required (IMGBB_API_KEY).
• Cloudflare R2: Ideal for S3-compatible persistent cache storage (R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET_NAME).

Variable Name	Type	Description	Default / Example
SPATIALPOSTERS_TMDB_KEY	Optional	Fallback TMDB v3 API key for single-user instance	your_tmdb_v3_key
SPATIALPOSTERS_MDBLIST_KEY	Optional	MDBList API key for aggregated rating scores	your_mdblist_key
SPATIALPOSTERS_TVDB_API_KEY	Optional	TVDB API key for TV show season orderings	your_tvdb_key
CLOUDINARY_CLOUD_NAME	Recommended	Cloudinary Cloud Name for persistent CDN uploads	your_cloud_name
CLOUDINARY_API_KEY	Recommended	Cloudinary API Key	your_api_key
CLOUDINARY_API_SECRET	Recommended	Cloudinary API Secret	your_api_secret
CLOUDINARY_URL	Alternative	Alternative single string format for Cloudinary	cloudinary://key:secret@cloudname
IMGBB_API_KEY	Optional	ImgBB API key for free image hosting	your_imgbb_api_key
R2_ACCOUNT_ID	Optional	Cloudflare R2 Account ID for S3 persistent cache	your_cloudflare_account_id
R2_ACCESS_KEY_ID	Optional	Cloudflare R2 Access Key ID	your_r2_access_key_id
R2_SECRET_ACCESS_KEY	Optional	Cloudflare R2 Secret Access Key	your_r2_secret_access_key
R2_BUCKET_NAME	Optional	Cloudflare R2 Bucket Name	spatialposters
KV_REST_API_URL	Optional	Upstash Redis REST API URL for KV store	https://xxx.upstash.io
KV_REST_API_TOKEN	Optional	Upstash Redis REST API Token	your_upstash_token
SPATIALPOSTERS_ADMIN_PIN	Optional	Set Admin Password/PIN to lock instance settings (only owner can modify)	mysecret2026
SPATIALPOSTERS_PUBLIC_INSTANCE	Optional	Set to 1 to enable public multi-user instance mode	1
SPATIALPOSTERS_ADMIN_TOKEN	Optional	Secret PIN/Token for protecting admin API routes	supersecret
SPATIALPOSTERS_DATA_DIR	Optional	Path to local persistent data storage directory	/data

---

🛡️ Admin Password Protection (SPATIALPOSTERS_ADMIN_PIN)

SpatialPosters features owner-only password protection to prevent unauthorized users from tampering with your self-hosted instance's settings.

Note

How Password Protection Works:

• Default Unlocked Mode (No Env Set): If SPATIALPOSTERS_ADMIN_PIN (or SPATIALPOSTERS_SITE_PASSWORD) is not set, SpatialPosters runs completely open and unlocked. First-time visitors will never be prompted for a password or PIN setup.
• Owner Controlled Protection (Env Set): To lock your studio workspace, set SPATIALPOSTERS_ADMIN_PIN=your_secret_password in your Vercel / server environment variables. Only you as the instance owner control access—no visitor can ever overwrite or set a random PIN!
• Session Persistence: Entering the correct password grants a secure 30-day session cookie, saving you from re-entering your password on every visit.

---

📺 Ecosystem Integration Guide

1️⃣ Stremio Addon Integration

1. Open SpatialPosters and configure your desired default poster styling in Settings.
2. Click Install Hub or copy your manifest URL:

   https://<your-domain>/c/<config_token>/manifest.json
   

3. Paste the URL into Stremio search bar to install SpatialPosters as an active catalog & artwork provider.

2️⃣ Jellyfin & Plex Media Server Integration

SpatialPosters exposes direct image endpoints that can be integrated into Jellyfin, Plex, or Emby:

https://<your-domain>/api/poster/movie/<tmdbId>
https://<your-domain>/api/poster/tv/<tmdbId>

• Jellyfin: Edit Metadata ➔ Images ➔ Enter the poster API URL or saved Cloudinary image URL.
• Plex: Edit Poster ➔ Enter custom URL.

---

💖 Support & Sponsorship

SpatialPosters is built with passion and provided 100% free and open-source under the AGPLv3 license.

If you love using SpatialPosters or want to support future open-source projects created by @TheAceOfficials, consider backing on Patreon:

🌟 Membership Tiers

• ☕ Coffee Supporter ($3/mo): Supporter credit in GitHub README & App UI + Early dev updates.
• 🔥 Priority Feature Requester ($5/mo): Fast-track feature requests & shape future project roadmaps.
• 👑 Supporter Hall of Fame ($10/mo): Official Sponsor Logo/Link credit across all @TheAceOfficials projects.

---

🤝 Acknowledgments & Upstream Attribution

A huge shoutout to the original Pictorium project created by @Eful97! SpatialPosters originally started out as a fork of their incredible artwork engine. They laid down a solid foundation, and we give full credit to the original developers for their work.

SpatialPosters actively honors and adapts selected core capabilities from the upstream Pictorium engine, including:

• 📦 Full-Space Configuration Backup & Restore: JSON export/import of poster mappings, server defaults, and user preferences.
• 🎨 Fanart.tv Poster Sourcing: Support for high-res artwork sourcing and custom project keys.
• 🖼️ TMDB Default Text Poster Toggle: Option to toggle between clean textless posters and original TMDB posters with text.
• 📜 Trakt, TVDB & IMDb Catalog Sourcing: Custom catalog imports from official Trakt/TVDB lists and IMDb CSV files.

Alongside these upstream capabilities, SpatialPosters incorporates custom features built for our community—such as direct r/SpatialPosters Reddit community syncing, Upstash KV indicators, custom admin PIN protection, and a liquid-glass UI overhaul.

Both projects are great open-source tools built for cinephiles. We highly encourage checking out both repositories!

---

📄 License

This project is licensed under the AGPLv3 License — see the LICENSE file for details.

---

Crafted with ❤️ by @TheAceOfficials

SpatialPosters — Elevate your Media Experience