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.

Features

This version (emby-wrapped) 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.
• URL parameters - Provide URLs with a pre-selected time-frame
• Emby authentication - Added security via Emby authentication. Users must log in to see stats
• Seerr integration - Optional Seerr integration showing number of requests and broken down by movie, series, and user
• Tracearr integration - The Emby Playback Reporting Plugin is no longer required - you can use history data from Tracearr instead
• 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
• Device breakdown - See which devices you watched on
• Live TV - See Live TV time watched and top 5 channels
• Share Cards - Download individual stat cards to share

Screenshots

Requirements

Emby Server Setup

1. Emby Server and API Key- Version 4.7+ recommended
   • Go to Emby Dashboard → API Keys
   • Create a new API key for "Emby Wrapped"
   • Copy the key for configuration
2. Playback Reporting Plugin (Required unless using Tracearr)
   • 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. Tracearr (optional)
   • If you use Tracearr integration (TRACEARR_URL + TRACEARR_API_KEY), Emby Wrapped can read playback history from Tracearr instead
   • If Tracearr usernames differ from current Emby usernames, use TRACEARR_USERNAME_ALIASES to map old names to current names
   • If both the Playback Reporting Plugin and Tracearr are configured, Tracearr data will be used
4. Seerr (optional)
   • Enable to view request stats

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

1. Create a docker-compose.yml file:

version: '3.8'
services:
  emby-wrapped:
    image: ghcr.io/ctznsniiips/emby-wrapped:latest
    container_name: emby-wrapped
    ports:
      - "3003:3003"
    environment:
      - EMBY_URL=http://your-emby-server:8096
      - EMBY_API_KEY=your-api-key-here
      - TMDB_API_KEY=    # Optional: for enhanced poster images
      - SEERR_URL=       # Optional: Overseerr/Jellyseerr URL for request stats
      - SEERR_API_KEY=   # Optional: Overseerr/Jellyseerr API key
      - TRACEARR_URL=    # Optional: Tracearr URL (uses Tracearr history instead of Playback Reporting)
      - TRACEARR_API_KEY= # Optional: Tracearr public API key (format: trr_pub_*)
      - TRACEARR_USERNAME_ALIASES= # Optional: oldname1:newname1,oldname2:newname2
      - PUBLIC_URL=      # Optional: for share links
      - CACHE_TTL=86400  # Optional
      - FILTER_USER_ID=  # Optional: filter by user's library
      - PORT=3003       # Optional: app listen port inside container
    volumes:
      - ./music:/app/static/music:ro  # Optional: custom background music
    restart: unless-stopped

1. Run:

docker compose up -d

1. Access at http://localhost:3003

Updating

Pre-built image:

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

Local Development

Prerequisites

• Node.js 18+
• npm or pnpm

Setup

1. Clone the repository:

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

1. Install dependencies:

npm install

1. Create environment file:

cp .env.example .env

1. Edit .env with your Emby server details:

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

1. Start development server:

npm run dev

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

Building for Production

npm run build
npm run preview

Configuration

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

General use

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

URL parameters

Provide time-specific URLs for your users

Add ?YYYY or ?MM-YYYY to your url to pre-select the time period where MM is the 2 digit month and YYYY is the 4 digit year

Example

http://yourip:3003?2025 - will pre-select the year 2025 review after the user logs in

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 (or that Tracearr is running and configured)
• 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! Feel free to submit a Pull Request. Please base any PRs on the beta branch.

License

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

Acknowledgments

• Thanks to davidtorcivia for the original emby-wrapped-ftp
• Additional thanks to tonghongte for their emby-wrapped-ftp fork
• Inspired by Spotify Wrapped
• Built for the Emby community
• Uses the Emby API for data retrieval
• Additional thanks to Tracearr and Seerr project contributors