ShowShark Server Features

Last updated on 

ShowShark Server is a macOS application that manages a media library, transcodes video and audio on the fly, and streams content to ShowShark Client apps over the local network.

Networking

  • WebSocket over TLS (WSS) for secure client-server communication
  • Optional plain WebSocket (WS) listener for reverse proxy setups (e.g., Caddy or nginx terminating TLS upstream)
  • Configurable ports for both listeners (default WSS: 18080, plain WS: 18081)
  • Bonjour/mDNS service advertisement for automatic server discovery by clients
  • Persistent server UUID across restarts so clients can identify the server reliably
  • Low-latency streaming optimizations on all listeners
  • Maximum 100 concurrent client connections, 5 per IP address
  • Slow operations (playback, thumbnails) run concurrently without blocking other client requests
  • HTTP polling server for watchOS clients: login, send/receive messages, 25-second long-poll for server pushes, 120-second inactivity timeout with automatic session eviction
  • WebSocket liveness handling: server correctly handles client ping/pong frames without disrupting the connection, and sends WebSocket Close frames on shutdown so clients are notified immediately
  • Graceful shutdown: connected clients receive close notifications before the server stops, enabling instant disconnection detection instead of waiting for timeouts

Authentication & Security

  • Password-based authentication with device name and device identifier tracking
  • Per-IP authentication throttling with escalating delays (1s to 8s) on failed login attempts, auto-expiring after 15 minutes
  • Session management with per-connection tracking
  • Known device registration with last-connected timestamps
  • Self-signed TLS certificate generation and keychain storage

Media Library

Scanning & Indexing

  • Recursive media file discovery across configured filesystem locations
  • Movie, TV show, and music library scanning with automatic content classification
  • TV show episode filename parsing: s03e12, s01e01-03 (ranges), e12, 3x12 formats
  • Music filename parsing: 01 - Song Title.mp3, 01. Title.flac
  • Blu-ray disc (BDMV) directory detection and indexing
  • Image files and photo directories automatically excluded from library scanning
  • Efficient duplicate detection for fast re-scans
  • Incremental scanning: metadata linking only runs for newly created records

Database

  • SQLite database for media library storage
  • Tables: movies, shows, episodes, files, artists, albums, songs, genres, people, and linking tables
  • Movie ratings: G, PG, PG-13, R, NC-17, NR, Unrated
  • TV ratings: TV-Y, TV-Y7, TV-G, TV-PG, TV-14, TV-MA, NR
  • Schema migrations for seamless upgrades across versions

Library Maintenance

  • Orphaned file detection and user-confirmed cleanup
  • Deleted-location cleanup for removed media locations
  • Excluded-directory cleanup
  • Image file cleanup for incorrectly-indexed records
  • Cascading deletion: removing a file cascades to its parent movie/episode/show if no files remain
  • Automatic daily cleanup scheduler (3:00 AM)
  • Multi-field search across titles, overviews, genres, actors, and years
  • Cross-type results: movies, shows, genres, actors, artists, albums, songs, photo albums
  • Genre-scoped browsing by media type (Movies, TV Shows, Music)
  • All genre lists fetched in a single request (movie, show, and music genres)
  • Music genre browsing with artist, album, and song results
  • Library stats: aggregate counts for movies, shows, episodes, artists, albums, songs
  • Detail queries: movie with cast, show with seasons/episodes, episode, album with songs, artist with discography, genre media, actor filmography

Metadata Providers

TMDB (The Movie Database)

  • Bearer token authentication
  • Movie and TV show search, detail retrieval with credits
  • Poster and backdrop images
  • Top 10 cast members with profile photos, character names, and ordering
  • US content certification from release dates and content ratings
  • Genre extraction

OMDB (Open Movie Database)

  • API key authentication (accepts both keys and URLs)
  • Rotten Tomatoes scores
  • MPAA and TV ratings
  • Genre and cast names

Hybrid Metadata Strategy

  • TMDB for images, cast photos, genres + OMDB for Rotten Tomatoes scores and ratings
  • Fallback: TMDB certification endpoints when OMDB is unavailable
  • Rate limiting: 1 request/second per provider to respect API limits
  • Disk-based metadata cache

Music Metadata

  • MusicBrainz for artist and album identification
  • Cover Art Archive for high-quality album art
  • Last.fm as fallback for album art
  • ID3v2, Vorbis Comment, and FLAC tag extraction (artist, album, title, track number, disc number, genre, duration, embedded album art)

Lyrics

  • LRCLib integration for synced lyrics
  • Time-synced lyrics with line-by-line timestamps
  • Plain text lyrics fallback
  • Automatic song info resolution from the library database when title/artist not provided
  • File-based lyrics caching

Person/Cast Metadata

  • Provider-agnostic storage (not locked to a specific metadata service)
  • Person photos proxied through server to prevent direct client access to external APIs

Video Transcoding

Input Formats

  • Containers: MKV, MP4, MOV, AVI, WebM, MPEG-PS (.vob), MPEG-TS (.ts/.m2ts), plus auto-detect
  • Video codecs: H.264, H.265/HEVC, MPEG-1, MPEG-2, MPEG-4/DivX/Xvid, DIV3/MSMPEG4v3, VC-1, VP8, VP9, AV1
  • Audio codecs: AAC, MP3, AC-3, E-AC-3, DTS, DTS-HD, DTS-HD Master Audio, Dolby TrueHD, FLAC, Vorbis, Opus, LPCM, WMA, MP1, MP2, ALAC

Output

  • Video: H.264 or H.265/HEVC via hardware encoding (automatically negotiated with client)
  • Audio: AAC at 44.1kHz stereo
  • Client-configurable target bitrate, output dimensions (4K/1080p/720p), and encoding quality

Audio Processing

  • DC offset removal for clean downmixed audio
  • Channel-aware surround-to-stereo downmix gain compensation (mono through 7.1 surround)
  • Audio packet coalescing for efficient network delivery (~5 sends/second instead of ~31)
  • Float clamping, NaN replacement, and channel-mask handling for edge-case audio formats

Video Processing

  • Pixel aspect ratio correction (non-square pixels normalized to square)
  • Timestamp interpolation for B-frame videos with missing timestamps
  • Subtitle burn-in for bitmap subtitle formats (PGS, VobSub)
  • Client-side text subtitle extraction for SRT, ASS, and SSA formats (instant language switching)
  • HDR content detection
  • Optimized processing order: scaling runs before color conversion so smaller frames are processed first (4x fewer pixels for 4K-to-1080p)

Codec Compatibility

  • AC-3/E-AC-3 Dolby decoder selection: selects the correct decoder based on actual stream capabilities, preventing failures on AVI files with AC-3 audio
  • Dolby renegotiation handling: streams that start as AC-3 and switch to E-AC-3 mid-playback are handled gracefully without decoder lock-in
  • H.264 software decode fallback: files with malformed configuration records that cause hardware decode to fail are automatically routed through software decoding
  • MPEG-PS container detection: identifies MPEG Program Stream content by inspecting the actual stream data, correctly handling files mislabeled with incorrect extensions
  • DIV3/MSMPEG4v3 detection: legacy Microsoft video codecs are properly identified and routed through the correct decode path
  • x264 software encoder fallback: legacy MPEG-PS sources that crash the hardware encoder are automatically routed through software encoding
  • AV1 hardware decode (M3+ Macs): automatically uses hardware AV1 decoding on Apple Silicon M3 and later; falls back to software decoding on M1/M2

Streaming Pipeline

  • Full teardown-and-restart architecture: pause = stop + remember position; resume/seek = start at new position
  • Single code path for seek, resume, reconnection, and initial playback
  • Real-time pacing: audio and video streams delivered at playback speed
  • Startup burst: initial 5-second burst for fast client buffer fill, with automatic exit on queue pressure to prevent overloading
  • Startup keyframe gating: video waits for first keyframe before streaming begins; audio held until video anchor is established
  • Adaptive startup buffer sizing based on actual source framerate and audio cadence
  • Optimized network delivery path eliminates unnecessary overhead during streaming
  • Real-time transcoding performance monitoring: stops session if throughput falls below 70% realtime

Adaptive Bitrate (ABR) Streaming

  • Automatic bitrate adjustment during playback based on real-time client feedback (buffer level and network throughput)
  • Buffer-zone logic: critically low buffers trigger immediate quality reduction, healthy buffers allow gradual increases, high buffers increase regardless
  • Resolution-based maximum bitrate ceilings: 4K = 20 Mbps, 1080p = 10 Mbps, 720p = 6 Mbps, 480p and below = 3 Mbps
  • Smooth transitions: bitrate changes are quantized and smoothed to avoid visible quality oscillation
  • Conservative 2 Mbps starting bitrate that works on any connection; fast connections ramp to ~10 Mbps in about 48 seconds
  • Adaptive mode enabled by default; fixed bitrate available as an option
  • Live encoder bitrate displayed in the Status tab during active sessions

Automatic Codec Selection

  • Server validates encoder availability before accepting client codec preference
  • Automatically selects H.264 encoding when the source uses software decoding (AV1 on M1/M2, VP9, MPEG-2, etc.), since hardware HEVC encoding is much slower from CPU-decoded sources
  • Automatically uses HEVC when hardware decoding is available (the fast path)

Demo Mode

  • 15-minute stream limit for non-upgraded users
  • Clear end-of-stream notification explaining the demo limit
  • Limit removed immediately if server is upgraded mid-session

HLS Transcoding (watchOS)

  • HLS streaming for watchOS clients using the native video player
  • HTTP file server for HLS segment delivery
  • 2-second target segment duration for fast startup (~2 seconds to first segment)
  • Output sized to 198x242 at 400 kbps with letterboxing (aspect ratio preserved)
  • Real-time pacing so segments are produced at playback speed
  • Explicit demuxer and decoder chains per format (fixes audio corruption from automatic codec selection)
  • Playlist configured so the watch player buffers from the start instead of chasing a live edge
  • All segments retained on disk for clients that fall behind real-time
  • Waits for first segment before sending URL to client (prevents initial playback errors)
  • HLS sessions visible in server Status tab with codec, position, and progress tracking
  • Configurable HLS toggle and port in server Settings

Blu-ray Disc Playback

  • Blu-ray disc folder structure (BDMV) detection, scanning, and playback
  • Title scanning with 120-second minimum filter (excludes menus and trailers)
  • Content classification: movie (single or 2 longest titles), TV season (multiple similar durations)
  • Chapter, clip, and stream metadata extraction
  • Seamless multi-clip playback
  • Pre-scan for accurate keyframe and audio positions before playback starts
  • Multi-codec keyframe detection: H.264, HEVC, MPEG-1/2, VC-1
  • Accurate A/V synchronization using domain-independent content timing (eliminates ~1-2 second desync)
  • Corrupt leading frame prevention after seeks
  • Blu-ray-specific thumbnail generation with chapter/clip offset mapping
  • Virtual path convention: #bdmv suffix with optional :titleN for specific titles

iCloud Photos Integration

  • Photos framework integration with authorization management
  • Album browsing: My Albums, Shared Albums, Smart Albums
  • Pagination for large albums
  • Album search with case-insensitive matching
  • High-quality image fetching with iCloud network access
  • Video export to temporary directory
  • EXIF metadata extraction: date taken, GPS coordinates
  • Automatic temp file cleanup on app startup

Thumbnail Generation

  • Video thumbnail generation at specified time offsets
  • Batch thumbnail generation: reuses a single pipeline for efficiency, seeks in sorted order
  • One thumbnail pipeline at a time to prevent resource contention
  • Non-blocking: thumbnail generation runs in the background without delaying other requests
  • Album art thumbnails served from the library database
  • Image thumbnails with hardware-accelerated scaling and EXIF orientation support
  • Person photo thumbnails proxied from metadata providers
  • iCloud photo thumbnails
  • Photo metadata extraction: EXIF date, GPS coordinates (only for full-size views, not grid thumbnails)
  • Disk caching for generated thumbnails
  • Automatic failure detection stops batch generation early when the end of a video is reached

Channels

Video Channels

  • Virtual TV channels with 24-hour scheduled programming from the media library
  • Content filtering: by genre, actor, movie title, show title, media path, content rating, media type
  • Blacklist support for excluding specific content
  • Sorted (alphabetical) and randomized scheduling modes
  • Anti-repetition logic to avoid scheduling the same content consecutively
  • Hourly schedule refresh
  • Persistent schedules across restarts

Music Channels

  • Continuous music playback channels
  • Filtering by artist, album, song, and genre
  • Blacklist support for excluding specific songs

Photo Channels

  • Synchronized photo slideshow channels from filesystem folders and/or iCloud Photo Library albums
  • Deterministic scheduling: all clients show the same photo at the same time
  • Configurable slide interval (5-60 seconds)
  • Maximum 10,000 items per channel
  • Automatic shuffle rotation after full collection cycle
  • Hybrid source support: filesystem images + iCloud album assets

Channel Operations

  • Create, edit, and delete all channel types
  • Channels sorted alphabetically
  • Current program info with offset and remaining time
  • Channel thumbnail generation
  • Program guide with time range queries (overview, content rating, Rotten Tomatoes score, artist/album info)

Content Discovery / Recommendation Engine

Discovery Modes

  • Similar To: Find the most similar titles in your library to a seed movie or show, scored by keyword overlap, genre overlap, cast overlap, year proximity, and rating proximity. Returns the top 10 matches
  • By Feel: Filter your library by time commitment (quick / medium / long / epic) and mood (light & fun, intense, thought-provoking, heartwarming, dark & edgy); when more than 10 candidates match, a side-by-side comparison flow narrows the results
  • By Genre: Top 20 titles in a selected genre sorted by rating

Engine Infrastructure

  • Session management with automatic 10-minute expiry
  • Comparison flow tracks previously shown titles to ensure fresh candidates each round
  • TMDB keyword and rating data fetched during library scanning
  • Dedicated message types for recommendation sessions, picks, and skips

Play History

  • Server-backed play history shared across all connected devices
  • Per-client, per-file tracking for movies, shows/episodes, and music
  • Music history collapsed to one entry per album (songs without album metadata create individual entries)
  • Add, retrieve, delete, and update playback position
  • Periodic and final offset updates from client during playback
  • Library context (movie, show, episode, artist, album, song) preserved per entry for navigation back to library views
  • Channel-context playback writes history entries like library playback

File Browsing

  • Virtual path system mapping client paths to filesystem paths
  • Root listing with configured locations, custom display names, and custom SF Symbol icons
  • Recursive directory browsing within locations
  • Pagination support for large directories and iCloud photo albums
  • BDMV directories presented as single playable items (not navigable as folders)
  • Library IDs (movie, show, episode, album) populated on browse entries for client-side library navigation
  • iCloud Photos browsing via virtual path
  • Supported file extensions:
    • Video: .mp4, .m4v, .mov, .avi, .mkv, .wmv, .flv, .webm, .mpeg, .mpg, .3gp, .ts, .mts, .m2ts
    • Audio: .mp3, .m4a, .aac, .flac, .wav, .aiff, .ogg, .wma, .opus, .alac
    • Image: .jpg, .jpeg, .png, .heic, .heif, .gif, .tiff, .tif, .webp, .bmp

Server Administration UI

Status Tab

  • Server running/stopped indicator
  • Service status rows for WSS, optional WS, HTTP Polling (with client count), and HLS listeners
  • Active listener ports
  • Active transcoding sessions (video, audio, BDMV, HLS) with live position/duration and encoder bitrate
  • Connected device list with device name, IP address, and connection time
  • Firewall self-diagnostic: detects when macOS Application Firewall silently blocks incoming connections after an Xcode rebuild; runs automatically and alerts with fix instructions; auto-clears when resolved
  • Form/Section layout matching macOS System Settings appearance

Locations Tab

  • Add/remove media folders with persistent access
  • Custom display names per location (inline editing)
  • Custom SF Symbol icons per location (searchable picker with ~6,000 system symbols)
  • Alphabetical sorting by display name
  • Orphaned metadata cleanup for deleted locations
  • Form with grouped style

Library Tab

  • Trigger and monitor library scans with progress indicator
  • Library statistics: counts for movies, shows, episodes, artists, albums, songs
  • Manual database cleanup with confirmation
  • Library validation: test-transcode indexed video files with live pass/fail progress, persisted results to disk, mutual exclusion with scan/cleanup operations; validates regular files and BDMV discs
  • Validation results sheet with search filter, per-entry removal, and summary counts
  • Split clear actions: "Clear History" resets all results, "Clear Errors" removes only failures (so they can be re-validated while keeping successful results)
  • Resume button to continue a stopped validation run
  • "View Current Failures" button shown only when there are actual failures
  • Empty state instructions when no locations or media are configured
  • Form with grouped style

Channels Tab

  • Video, Music, and Photo channel editors with full filter configuration
  • Channel list management (create, edit, delete)
  • Manual schedule refresh
  • Form with grouped style

Providers Tab

  • TMDB and OMDB provider configuration with API key entry
  • Two-step type selection flow (Movie & TV Show vs. Music sections)
  • Provider status display
  • Quick link to provider websites
  • Lyrics provider configuration (LRCLib)
  • TMDB API key guidance with step-by-step instructions
  • Form with grouped style

Devices Tab

  • Known device list with name, identifier, and last connected time
  • Grouped into time-based sections: Today, Yesterday, and Earlier
  • Record counts displayed in section headings
  • Form with grouped style

Settings Tab

  • WSS port configuration with validation
  • Plain WS listener toggle and port
  • HTTP Polling port configuration with cross-port conflict detection
  • HLS service toggle and port configuration
  • Master password management with reveal/hide toggle

About Tab

  • App name, version, copyright, and support links (email + website URL)
  • Privacy policy and terms of service links
  • Open-source license attribution (GStreamer LGPL, SQLite public domain)
  • Log submission: toggle file-based logging with 24-hour auto-disable, daily rolling log files, compressed upload with reference ID, context sheet for name/email/issue description

Upgrade Tab

  • License status display
  • Purchase flow
  • Apple Sign In authentication

Licensing

  • Sign in with Apple authentication
  • Server update notifications sent to clients after login

Server Log Gathering

  • File-based logging with daily rolling files and 24-hour auto-disable toggle
  • Log filtering by timestamp for gathering specific time ranges
  • Compressed upload to ShowShark support service with metadata
  • 8-character reference ID returned to user with Copy button

Directory Exclusion

  • Exclude specific directories from library scanning while keeping them browsable
  • Persistent exclusion bookmarks
  • Excluded directories skipped during scanning and cleanup