Emby Wrapped (Enhanced)

A beautiful, Spotify Wrapped-style year-in-review experience for your Emby media server. This fork includes enhanced music statistics, improved image handling, and more detailed viewing patterns.

Fork Improvements

This version (emby-wrapped-ftp) adds several features and improvements over the original:

• Enhanced Music Statistics - Detailed breakdown of top artists and tracks with full image support.
• Image Proxy & Caching - Built-in image proxy to solve CORS issues and provide persistent caching for faster loading.
• Flexible Time Ranges - Support for both yearly and monthly "Wrapped" views.
• Library Filtering - Use FILTER_USER_ID to restrict displayed content (e.g., to hide NSFW libraries).
• High-Quality Visuals - Automatically fetches higher resolution posters and artist images.
• Improved Error Handling - Robust handling of missing images and server connection issues.

Screenshots

Features

• Total Watch Time - See how many days/hours you've spent watching
• Top Shows and Movies - Your most-watched content with beautiful poster displays
• Genre Breakdown - Discover your viewing preferences
• Viewing Patterns - Peak hours and favorite days of the week
• Viewing Personality - Fun personality type based on your habits
• Binge Sessions - See your longest viewing marathons
• Monthly Journey - Track your viewing across the year
• Share Cards - Download individual stat cards to share

Requirements

Emby Server Setup

1. Emby Server - Version 4.7+ recommended

2. Playback Reporting Plugin (Required)

   • Go to Emby Dashboard → Plugins → Catalog
   • Search for "Playback Reporting"
   • Install and restart Emby server
   • This plugin tracks detailed playback history needed for stats

3. API Key

   • Go to Emby Dashboard → API Keys
   • Create a new API key for "Emby Wrapped"
   • Copy the key for configuration

Quick Start with Docker (Recommended)

Option 1: Using Pre-built Image from GHCR (Easiest)

Pull the image from GitHub Container Registry and run:

1. Create a directory for your setup:

mkdir emby-wrapped && cd emby-wrapped

2. Create a docker-compose.yml file:

version: '3.8'
services:
  emby-wrapped:
    image: ghcr.io/tonghongte/emby-wrapped-ftp:latest
    container_name: emby-wrapped
    ports:
      - "3000:3000"
    environment:
      - EMBY_URL=http://your-emby-server:8096
      - EMBY_API_KEY=your-api-key-here
      - TMDB_API_KEY=   # Optional: for enhanced poster images
      - PUBLIC_URL=     # Optional: for share links
      - CACHE_TTL=86400 # Optional
      - FILTER_USER_ID= # Optional: filter by user's library
    volumes:
      - ./music:/app/static/music:ro  # Optional: custom background music
    restart: unless-stopped

3. Run:

docker compose up -d

4. Access at http://localhost:3000

Portainer: In Portainer → Stacks → Add stack → paste the above compose and set your EMBY_URL and EMBY_API_KEY in the environment section.

Option 2: Build from Source

1. Clone the repository:

git clone https://github.com/tonghongte/emby-wrapped-ftp.git
cd emby-wrapped-ftp

2. Create your environment file:

cp .env.example .env

3. Edit .env with your Emby server details:

EMBY_URL=http://your-emby-server:8096
EMBY_API_KEY=your-api-key-here
# Optional
TMDB_API_KEY=
PUBLIC_URL=

4. Build and run:

docker-compose up -d --build

5. Access at http://localhost:3000

Updating

Pre-built image:

docker-compose pull && docker-compose up -d

From source:

git pull && docker-compose up -d --build

Local Development

Prerequisites

• Node.js 18+
• npm or pnpm

Setup

1. Clone the repository:

git clone https://github.com/tonghongte/emby-wrapped-ftp.git
cd emby-wrapped-ftp

2. Install dependencies:

npm install

3. Create environment file:

cp .env.example .env

4. Edit .env with your Emby server details:

EMBY_URL=http://your-emby-server:8096
EMBY_API_KEY=your-api-key-here

5. Start development server:

npm run dev

6. Open http://localhost:5173 in your browser

Building for Production

npm run build
npm run preview

Configuration

Variable	Description	Required
EMBY_URL	Full URL to your Emby server (e.g., http://192.168.1.100:8096)	Yes
EMBY_API_KEY	API key from Emby Dashboard	Yes
TMDB_API_KEY	TMDB API key for enhanced poster images (get one free at themoviedb.org)	No
PUBLIC_URL	Public URL for share links (defaults to request origin)	No
ANALYTICS_SCRIPT	Analytics script tag (e.g., Umami, Plausible) to inject into page head	No
FILTER_USER_ID	Emby User ID to use for library filtering (useful for hiding NSFW content)	No
CACHE_TTL	Cache duration in seconds for statistics (default: 86400)	No

Background Music

Emby Wrapped supports custom background music during the presentation. To add your own tracks:

1. Create a static/music/ directory in the project
2. Add MP3 files to the directory
3. Music will automatically play during the wrapped experience

For Docker deployments, mount a volume to /app/static/music/ (see docker-compose example).

Usage

1. Navigate to the app in your browser
2. Select the time period (Year or Month) you want to view
3. Select your user from the list
4. Enjoy your personalized Emby Wrapped experience!
5. Use the Share button on any card to download it as an image

New in this Fork

Detailed changes can be found in the CHANGELOG.md.

Enhanced Music Experience

The music summary card now features:

• Artist & Track Thumbnails: Visual representation of your top music content.
• Proxy Handling: All images are proxied through the server to avoid CORS issues and ensure they load correctly even if your Emby server is behind a restrictive firewall.
• Dynamic Placeholders: Beautiful gradient placeholders if an image is missing.

Robust Backend

• Server-side Caching: Images are cached locally to reduce load on your Emby server and improve presentation speed.
• Improved API Client: Better handling of Emby's complex image API, including artist ID resolution.
• NSFW Filtering: Ability to filter the entire wrapped experience through a specific user's permissions via FILTER_USER_ID.

Tech Stack

• Framework: SvelteKit
• Styling: Tailwind CSS
• Animations: CSS animations + Svelte transitions
• Image Capture: html2canvas
• Fonts: Space Grotesk, JetBrains Mono

Security Considerations

• API keys are stored server-side only and never exposed to the client
• All Emby API requests are proxied through the server
• No user data is stored - stats are fetched fresh each time
• CORS is handled server-side

Troubleshooting

"No users found"

• Verify your EMBY_URL is correct and accessible
• Check that your EMBY_API_KEY has sufficient permissions

Stats seem incomplete

• Make sure the Playback Reporting plugin is installed
• The plugin needs time to collect data - it only tracks plays after installation
• Check the date range - Emby Wrapped shows current year stats

Images not loading

• Ensure your Emby server is accessible from the Emby Wrapped container/server
• Check for any firewall rules blocking the connection

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by Spotify Wrapped
• Built for the Emby community
• Uses the Emby API for data retrieval