Subtitles

​

Subtitle Sources

​

Automatic Subtitle Discovery

​

Discovery Process

1. Check Database: Looks for previously discovered subtitles
2. Scan Embedded: Extracts subtitle tracks from video file metadata
3. Scan Sidecar: Looks for .vtt, .srt, .ass files in same directory
4. Background Fetch: Continues discovery in background while you watch

​

Supported Formats

​

Embedded Formats

• SubRip (SRT): Extracted from video containers
• ASS/SSA: Advanced SubStation Alpha (styling preserved)
• WebVTT: Native web format
• DVB Subtitles: Bitmap-based subtitles

​

Sidecar Formats

• WebVTT (.vtt): Preferred format, works natively in browser
• SubRip (.srt): Auto-converted to VTT on server
• ASS (.ass): Advanced styling, converted to VTT

​

File Naming Conventions

movie.mp4
movie.en.vtt          // English subtitles
movie.es.srt          // Spanish subtitles
movie.en.forced.vtt   // Forced English subtitles

show-s01e01.mkv
show-s01e01.en.vtt
show-s01e01.en.sdh.vtt  // SDH (Hearing Impaired)

​

Subtitle Selection

​

Player Subtitle Menu

1. Click the CC button in player controls
2. View list of available subtitle tracks
3. Select desired language
4. Subtitles activate immediately

​

Subtitle Track Display

• Language: Full language name (e.g., “English”, “Spanish”)
• Source: Where it came from (embedded, sidecar, OpenSubtitles)
• Type: Regular, forced, or SDH (hearing impaired)
• Format: VTT or SRT

​

Default Subtitles

​

OpenSubtitles Integration

​

Configuration

1. Navigate to Settings
2. Enter OpenSubtitles API key
3. (Optional) Enter username and password for premium features
4. Save settings

​

Searching for Subtitles

1. Click Find Subtitles
2. Select target languages (defaults to English)
3. View search results
4. Click Download on desired subtitle

​

Search Criteria

• TMDB ID: Most accurate matching
• Title + Year: Fallback if no TMDB ID
• Season + Episode: For TV shows
• Language: Filter by desired languages

​

Download Process

1. Plank fetches subtitle file from OpenSubtitles
2. Converts to WebVTT format (if needed)
3. Saves to library directory as sidecar file
4. Adds entry to subtitles database table
5. Immediately available in player

​

Manual Subtitle Upload

​

Upload Workflow

1. Navigate to media detail page
2. Click Upload Subtitle
3. Select .vtt or .srt file
4. Choose language
5. (Optional) Mark as default or forced
6. Click Upload

​

Supported Upload Formats

• WebVTT (.vtt): Uploaded as-is
• SubRip (.srt): Auto-converted to VTT
• ASS/SSA (.ass/.ssa): Converted to VTT (styling may be lost)

​

Subtitle Management

​

Viewing Subtitles

1. Open media detail page
2. Scroll to “Subtitles” section
3. View list of available tracks

​

Deleting Subtitles

1. Click delete icon next to subtitle
2. Confirm deletion
3. Subtitle file removed from library

​

Setting Default Subtitle

1. Click “Set as Default” on subtitle track
2. Player will auto-select this track on playback

​

Forced Subtitles

• Useful for movies with mixed languages
• Only shows when non-English dialogue appears
• Mark as forced during upload or download

​

Database Schema

subtitles:
- id: unique identifier
- mediaId: links to media item
- episodeId: (optional) links to specific episode
- language: ISO 639-1 code (e.g., "en")
- label: display name (e.g., "English")
- source: embedded | sidecar | opensubtitles | manual
- format: vtt | srt
- filePath: path to subtitle file (for sidecar)
- streamIndex: stream index (for embedded)
- isDefault: auto-select flag
- isForced: forced subtitle flag

​

Subtitle Tracks API

GET /api/media/{id}/subtitles?episodeId={episodeId}

​

Subtitle Format Conversion

​

Why WebVTT?

• Native browser support
• No conversion needed at runtime
• Supports styling and positioning
• Standardized timing format

​

Conversion Process

1. SRT → VTT: Converts timestamp format and headers
2. ASS → VTT: Extracts text, may lose styling
3. Embedded → VTT: Extracts from video container

​

FFmpeg Integration

ffmpeg -i video.mkv -map 0:s:0 -c:s webvtt output.vtt

​

Performance Optimization

​

Lazy Loading

• Player starts immediately
• Subtitles appear as they’re discovered
• No blocking on slow file scans

​

Caching

• Database stores subtitle metadata
• Prevents re-scanning files
• Instant loading on subsequent plays

​

Concurrent Discovery

• Embedded track extraction
• Sidecar file scanning
• OpenSubtitles search (if enabled)

​

Advanced Features

​

SDH (Subtitles for Deaf and Hard of Hearing)

• Sound effect descriptions [door slams]
• Speaker identification
• Music and ambient noise notation

​

Multi-Language Support

• ISO 639-1 language codes
• Full language names in player UI
• Search by multiple languages simultaneously
• No limit on number of subtitle tracks

​

Subtitle Synchronization

• Use player’s subtitle offset feature (if available)
• Download alternate subtitle file
• Manually edit .vtt file timing (advanced)

​

Troubleshooting

​

Subtitles Not Showing

• Must be in same directory as video
• Filename must match video filename
• Extension must be .vtt, .srt, or .ass

• Subtitle may not be discovered yet
• Refresh the page to trigger discovery
• Check browser console for errors

​

Embedded Subtitles Missing

• Verify FFmpeg is available on server
• Check server logs for FFmpeg errors

• Some subtitle codecs may not be supported
• Extract manually and upload as sidecar

​

OpenSubtitles Not Working

• Verify API key in settings
• Check OpenSubtitles account status
• API key may be rate-limited

• Media must have TMDB metadata
• Re-add media to fetch TMDB ID
• Manually search on OpenSubtitles.com

​

Subtitle Encoding Issues

• Most subtitles should be UTF-8
• Convert to UTF-8 before uploading
• Use tool like iconv on Linux/Mac

​

Sync Issues

• Download different subtitle file
• Manually adjust .vtt timestamps
• Use subtitle editing tool (Subtitle Edit, Aegisub)

​

Next Steps