series-player

Automated binge-watching system with per-episode intro/outro detection and progress tracking.

Quick Start

Global Installation (Recommended)

# Run the global installer
powershell -ExecutionPolicy Bypass -File install_global.ps1

This will:

1. Add binge command to your PATH
2. Install mpv Lua script
3. Allow you to run binge from anywhere

After installation, restart your terminal and use:

# From any directory
binge detect "path\to\series" 35
binge watch "path\to\series"

# Or use current directory
cd "C:\TV Shows\The Office\Season 3"
binge detect . 35
binge watch .

Automated Setup (For Development)

# Run the setup script
setup.bat

This will:

1. Create conda environment with Python 3.9
2. Install all Python dependencies
3. Check for FFmpeg and mpv

Manual Setup

# 1. Install mpv script (one-time)
binge.bat install

# 2. Detect intros/credits
binge.bat detect "path\to\series" 35

# 3. Start watching
binge.bat watch "path\to\series"

Features

✅ Manual Intro Sample - Provide your own intro clip for perfect matching
✅ GUI Intro Extractor - Easy-to-use interface for creating intro samples
✅ IntroDB Integration - Crowdsourced TV show timestamps via IntroDB API
✅ Anime-Skip Integration - Anime timestamps from anime-skip.com
✅ Smart Fallback - Falls back to local audio fingerprinting if API unavailable
✅ API Response Caching - 7-day cache to minimize API calls
✅ Per-Episode Detection - Each episode analyzed individually
✅ Fine-Grained Precision - Timestamps accurate to 0.01 seconds
✅ Smart Intro Detection - Audio fingerprinting finds intros at different positions
✅ Configurable Credits - Set credits offset (e.g., 35s from end)
✅ Progress Tracking - Resume exactly where you left off
✅ Auto-Skip Watched - Automatically skips completed episodes
✅ Series Configuration - JSON config for per-series settings

Project Structure

series-player/
├── bin/                    # Executables and main scripts
│   ├── detect.py          # Intro/outro detection
│   ├── create_config.py   # Configuration creator
│   ├── watch.bat          # Watch launcher
│   └── install_script.ps1 # Lua script installer
├── scripts/               # Lua scripts for mpv
│   └── watch_progress.lua # Auto-skip and progress tracking
├── src/                   # Source code (for future modules)
├── tests/                 # Test fixtures
│   └── fixtures/          # Sample video files
├── binge.bat              # Main entry point
└── README.md

Installation

Fresh System Setup (Windows)

If you're setting up on a new system without any prerequisites:

1. Install Miniconda (Python Environment Manager)

# Download and install from: https://docs.conda.io/en/latest/miniconda.html
# Or use winget:
winget install Anaconda.Miniconda3

2. Install Scoop (Package Manager)

# Run in PowerShell:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

3. Install FFmpeg and mpv

scoop bucket add extras
scoop install ffmpeg
scoop install extras/mpv

4. Setup Python Environment

# Navigate to project directory
cd path\to\series-player

# Create conda environment
conda create -p ./.conda python=3.9 -y

# Activate environment
conda activate ./.conda

# Install Python dependencies
pip install -r requirements.txt

5. Install mpv Lua Script

binge.bat install

Quick Setup (If You Have Conda/Scoop)

# 1. Setup Python environment
conda create -p ./.conda python=3.9 -y
conda activate ./.conda
pip install -r requirements.txt

# 2. Install system dependencies (if not installed)
scoop install ffmpeg extras/mpv

# 3. Install mpv script
binge.bat install

Verify Installation

# Check Python packages
python -c "import numpy, scipy, librosa, ffmpeg; print('✓ Python packages OK')"

# Check FFmpeg
ffmpeg -version

# Check mpv
mpv --version

Usage

Method 1: Manual Intro Sample (Most Accurate!)

Step 1: Extract Intro Sample

# Navigate to your series folder
cd "C:\TV Shows\The Office\Season 3"

# GUI Method (Easiest)
# Select any episode from the series, specify start time and duration
.\extract_intro_gui.ps1

# Or CLI Method
.\extract_intro.bat "episode01.mkv" 65 27
# Where: 65 = start time in seconds, 27 = duration in seconds

This creates .intro_sample.wav in the series folder.

Step 2: Run Detection (Auto-detects the sample)

binge.bat detect "C:\TV Shows\The Office\Season 3" 35
# The intro sample is automatically detected and used!

Method 2: Automatic Detection

# Auto-detect with API lookup first, then local fallback
binge.bat detect "C:\TV Shows\The Office\Season 3" 35

# Skip API, use local detection only
binge.bat detect "C:\TV Shows\The Office\Season 3" 35 --no-api

Watch Series

binge.bat watch "C:\TV Shows\The Office\Season 3"

Configure Series

# Create/update configuration
binge.bat config "C:\TV Shows\The Office\Season 3" 35

How It Works

Detection (detect.py)

1. API Lookup - Queries anime-skip.com for crowdsourced timestamps
2. Fallback to Local - If API unavailable, extracts intro reference from first episode
3. Audio Fingerprinting - Uses chromagram-based fingerprinting to find intro in each episode
4. Credits Calculation - Calculates credits position as offset from end (configurable)
5. Caching - Saves API responses (7-day TTL) and detection results to .intro_cache_v2.json
6. Configuration - Creates .series_config.json with settings

Playback (watch_progress.lua)

1. Loads configuration and detection cache
2. Skips to first unwatched episode
3. Monitors playback position in real-time
4. Auto-skips intros and credits based on config
5. Saves progress every 10 seconds to .watch_progress.json
6. Resumes from saved position on restart

API Integration

The system now supports crowdsourced intro/outro timestamps from multiple sources:

IntroDB (TV Shows)

IntroDB is a crowdsourced database for TV show intro timestamps.

How It Works:

1. API-First Approach - Queries IntroDB using IMDb IDs
2. Automatic Fallback - Falls back to local detection if no data available
3. Community Contribution - You can submit your detected timestamps to help others

Setup:

# Set your IntroDB API key (get one at introdb.app)
$env:INTRODB_API_KEY="idb_your_key_here"

# Or add to your PowerShell profile for persistence

Supported Shows:

• The Office (US) - tt0386676
• Breaking Bad - tt0903747
• Game of Thrones - tt0944947
• Stranger Things - tt4574334
• And more (see src/introdb_client.py for full list)

Anime-Skip (Anime)

Anime-Skip provides timestamps for anime series.

How It Works:

1. Queries anime-skip.com GraphQL API
2. 7-day response caching to minimize requests
3. Automatic fallback to local detection

Benefits

• Instant Detection for popular shows (no processing time)
• Community-Verified timestamps from thousands of users
• Bandwidth Efficient with response caching
• Always Works with automatic fallback to local detection

Usage

# Default: Try API first, fallback to local
binge.bat detect "path\to\series" 35

# Skip API, use local detection only
python bin\detect.py "path\to\series" --no-api --credits-offset 35

Configuration Files

Each series folder contains:

.series_config.json - User settings

{
  "credits_offset": 35,
  "auto_skip_intro": true,
  "auto_skip_credits": true,
  "series_name": "The Office S03"
}

.intro_cache_v2.json - Detected timestamps (auto-generated)

{
  "Episode01.mkv": {
    "intro_start": 100.45,
    "intro_end": 125.99,
    "outro_start": 1282.44,
    "duration": 1317.44,
    "source": "api"
  }
}

.watch_progress.json - Watch progress (auto-updated)

{
  "Episode01.mkv": {
    "position": 1282,
    "duration": 1317,
    "percent_complete": 97,
    "is_complete": true,
    "timestamp": 1769001603
  }
}

Troubleshooting

Python Environment Issues

"conda: command not found"

# Restart PowerShell after installing Miniconda
# Or manually add to PATH:
$env:PATH += ";C:\Users\YourName\miniconda3\Scripts"

"Module not found" errors

# Make sure conda environment is activated
conda activate ./.conda

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

FFmpeg/mpv Issues

"ffmpeg: command not found"

# Install via Scoop
scoop install ffmpeg

# Or download from: https://ffmpeg.org/download.html

"mpv not found"

scoop bucket add extras
scoop install extras/mpv

Detection Issues

"Intro not found" for all episodes

• Intro might be too short (<20s) or too long (>90s)
• Try with a different series first to verify setup
• Check if audio track exists: ffmpeg -i episode.mkv

Wrong intro positions

# Re-run detection with --force
binge.bat detect "path\to\series" 35

Playback Issues

Lua script not working

# Verify installation
dir "$env:APPDATA\mpv\scripts\skip_intro_outro.lua"

# Or for Scoop mpv:
dir "$env:USERPROFILE\scoop\apps\mpv\current\portable_config\scripts\skip_intro_outro.lua"

# Reinstall
binge.bat install

Progress not saving

• Check if .watch_progress.json is created in series folder
• Ensure series folder is writable
• Press ` in mpv to see console logs

Development

Project Structure

series-player/
├── bin/              # Main scripts
├── scripts/          # Lua scripts for mpv
├── src/              # Future Python modules
├── tests/            # Test fixtures
├── .conda/           # Python environment (gitignored)
├── requirements.txt  # Python dependencies
└── binge.bat         # Main entry point

Running from Source

# Activate environment
conda activate ./.conda

# Run detection directly
python bin\detect.py "path\to\series" --credits-offset 35

# Run config creator
python bin\create_config.py "path\to\series" 35

Workflow

See GUIDE.md for detailed workflow instructions and prompt library.

Quick start:

1. Tell your AI agent: "Read AGENTS.md, create CONTEXT.md and TASKS.md"
2. Define your objectives in CONTEXT.md
3. Let the agent populate TASKS.md with atomic tasks
4. Start executing tasks one at a time

Rules

This project follows strict task management rules defined in AGENTS.md:

• Exactly 1 task in Active at a time
• Every task broken into 2-5 atomic sub-steps
• Automatic commits after each sub-step
• Sequential sub-step completion (no skipping)
• Environment: PowerShell (Windows)

For the complete rule set, see AGENTS.md.