Apple TV 4K & Video Playback Diagnostics
Micro-Stutter / Judder & Native Refresh Rate Matching
If you observe periodic frame pacing stutters (typically occurring every 41 seconds on 23.976 fps content displayed at 60 Hz), your Apple TV display output has not synced with the master film timeline. This occurs due to standard 3:2 pulldown interpolation.
1. Open Apple TV Settings > Video and Audio > Match Content.
2. Set Match Frame Rate to ON.
3. Set Match Dynamic Range to ON.
How Velis Handles Timing: When Match Frame Rate is enabled, Velis uses AVFoundation display timing protocols to request instantaneous HDMI mode switching to exactly match source timestamps (23.976Hz, 24.000Hz, 50.000Hz PAL, or 59.940Hz), eliminating frame duplication judder completely.
Dynamic Range, Dolby Vision Fallback & SDR Tone Mapping
Washed out colors, elevated black floors, or dark greenish/purplish tints during 4K playback indicate a dynamic range metadata mismatch:
- Dolby Vision Profile 5 vs. Profile 8: Profile 5 uses proprietary ICtCp color space with zero embedded HDR10 fallback matrix. Profile 8 contains a standard Rec.2020 HDR10 base layer. When streaming Profile 5 to an unsupported HDR10-only or SDR display, Velis utilizes a dedicated Metal compute shader to convert ICtCp metadata into Rec.709 color primaries in real-time, preventing purple tint discoloration.
- HDMI EDID Negotiation: If your AV receiver sits between Apple TV and an OLED/Mini-LED panel, verify that the receiver's HDMI port format is toggled to
"Enhanced"or"8K/4K 120Hz"to avoid clipping 10-bit and 12-bit chroma signals. - Metal-Based SDR Tone Mapping: When playing 1,000 to 4,000 nit master files on an SDR monitor or standard MacBook display, Velis executes a modified ACES (Academy Color Encoding System) tonemapping curve via Metal Performance Shaders to preserve shadow detail without blowing out highlights.
Codec & Container Direct Play Pipeline
Velis employs a hybrid dual-engine rendering architecture to guarantee that your server never transcodes:
Handles H.264, HEVC (Main, Main 10), and Apple ProRes directly on dedicated hardware VPU silicon with zero CPU overhead and maximum battery efficiency.
Engages custom FFmpeg demuxers and Metal texture buffers for 10-bit AV1, VC-1, VP9, and complex High-Tier MKV containers that standard Apple players reject.
Audio Architecture & Passthrough
Understanding tvOS Audio Daemons: Bitstream vs. Multichannel LPCM
A common query from home theater enthusiasts is: "Why does my AV receiver display 'Multi-Ch PCM' instead of 'Dolby TrueHD' or 'DTS-HD MA' when streaming from Apple TV 4K?"
The Technical Cause: Apple tvOS does not allow raw bitstream passthrough for TrueHD or DTS-HD to third-party apps because tvOS reserves bitstream audio pipelines for its internal system mixing daemon (which mixes Siri feedback, navigation clicks, and Spatial Audio metadata).
Zero Loss of Audio Fidelity: Velis uses lossless libavcodec to decode raw 24-bit/192kHz TrueHD and DTS-HD MA bitstreams directly on your Apple hardware into uncompressed Linear PCM (LPCM 7.1) before sending it over HDMI eARC. Every single bit of audio sample data is preserved bit-for-bit with zero dynamic compression.
Spatial Audio & Atmos: Dolby Atmos over Dolby Digital Plus (E-AC-3 JOC) from streaming services is natively supported. Lossless Dolby TrueHD + Atmos metadata on disk will play as full lossless 7.1 LPCM surround, with bed and surround channels intact.
AV Receiver Latency & Audio Delay Offset
Complex video post-processing on modern 120Hz panels can cause video to render slightly after audio has already outputted to your soundbar or receiver:
- In-Player Audio Offset Controller: During playback, swipe down or press the Audio Options button to access the
Audio Syncslider. You can advance or delay audio in micro-intervals of ±500ms in precise 10ms increments. - Persistent Server Memory: Velis caches your audio offset calibration on a per-codec basis in SQLite, meaning once you calibrate your receiver for TrueHD streams, you will never need to readjust it.
AirPods Spatial Audio & Dynamic Head Tracking
Velis supports dynamic spatial head tracking on AirPods Pro (all generations), AirPods Max, and Beats Fit Pro. If spatial tracking does not engage:
- Ensure your audio track is 5.1 or 7.1 surround sound (stereo tracks require selecting "Spatialize Stereo" in macOS/iOS Control Center).
- In tvOS Control Center, hold down the TV/Home button on your Siri Remote, highlight your AirPods, and verify that Spatial Audio is set to Head Tracked rather than Fixed or Off.
Network, Buffer & Storage Tuning
SMB2/SMB3 Tuning vs. WebDAV Chunking
When mounting direct local NAS storage, protocol selection significantly dictates file seek response and initial buffer fill rates:
proxy_buffering off; and client_max_body_size 0; are declared. Velis requests precise byte-ranges via HTTP 206 Partial Content headers; proxies that buffer the entire file before responding will cause seek timeouts.
Wi-Fi vs. Gigabit Ethernet Buffer Saturation
While Wi-Fi 6 (802.11ax) theoretically provides high bandwidth, intermittent RF interference, DFS radar channel hops, and high channel utilization often introduce packet jitter. During an 80+ Mbps REMUX playback session, even a 500ms packet stall will drain the AVFoundation hardware pipeline buffer, triggering a spinner.
Best Practice: Always use a direct Cat6 Gigabit Ethernet connection to your Apple TV 4K. If Wi-Fi is mandatory, configure Velis's buffer profile under Settings > Playback > Memory Buffer Size to Maximum (256 MB) to absorb wireless throughput dips.
Offline Downloads & Sandboxed Cache Management
On iOS, iPadOS, and macOS, media files downloaded for offline airplane playback are isolated within Velis's secure container sandbox (NSDocumentDirectory):
- Background Downloads: Due to iOS background task execution limits (
NSURLSessionConfiguration.background), large 40 GB downloads may pause if your device is low on battery or in Low Power Mode. Keep Velis in the foreground or connect to power when queuing multiple 4K downloads. - Storage Purge: Navigate to
Settings > Storage & Cacheto review individual downloaded files or tap "Purge Stream Cache" to instantly reclaim transient buffer blocks without deleting offline libraries.
Subtitle Engines & Typography
Advanced ASS/SSA Metal Vector Glyph Rendering
Most web-wrapped and generic media players choke on anime or international media featuring complex SSA/ASS typesetting (karaoke effects, custom embedded TrueType/OpenType fonts, and coordinate animations), causing massive frame rate drops down to 15 fps.
Velis's Solution: Velis incorporates an asynchronous Metal-accelerated subtitle engine based on libass. Vector glyph paths are tessellated and rendered directly in GPU texture memory as a zero-copy overlay on top of the video surface. Even scenes with 50+ concurrent animated text objects maintain a flawless 120 fps ProMotion refresh rate.
Subtitle Desync: If external subtitles lag behind the audio track, use the on-screen Subtitle Delay adjustment (±10 seconds in 100ms intervals) to immediately re-anchor dialogue to lip sync.
Character Encoding Fallbacks (UTF-8, Windows-1252, ISO-8859-1)
If your external .srt subtitles display garbled symbols (like é or ’), the file is encoded in a legacy single-byte character set rather than standard UTF-8. Velis includes an automatic Universal Charset Detector (UCD) heuristic: if confidence drops below 85%, you can manually force encoding in Settings > Subtitles > Default Text Encoding (supporting Cyrillic Windows-1251, Western Windows-1252, and Japanese Shift-JIS).
CloudKit & Ecosystem Continuity
Resolving Stalled iCloud KVS & CloudKit Sync
Velis uses Apple's native CloudKit Private Database and NSUbiquitousKeyValueStore (KVS) to synchronize watch timestamps, watched statuses, and server connections across your Mac, iPhone, iPad, and Apple TV without requiring a proprietary Velis account.
1. Verify you are signed in with the same Apple Account across both devices.
2. Open System Settings / iOS Settings > [Your Name] > iCloud > Saved to iCloud.
3. Ensure the toggle for Velis is switched to ON.
4. Check that low-power mode or battery saver is not disabling Apple push notification daemons (APNs).
Profile Isolation & Multi-Server Token Security
Each device's server credentials and Plex/Jellyfin tokens are securely bound to the hardware Keychain. When multiple Apple TV users switch tvOS Control Center profiles, Velis queries the current active NSHomeDirectory(), guaranteeing that private watch queues, adult media tags, and server passwords never bleed across household members.
Diagnostics & Direct Engineering Support
How to Export Anonymized Diagnostic Logs
When reporting a stubborn playback or networking bug, our engineers rely on low-level AVFoundation and FFmpeg frame logs. Velis features a built-in privacy filter that automatically scrubs all IP addresses, server domain names, and authentication tokens:
Navigate to the in-app Settings gear icon.
Scroll to the bottom and tap "Diagnostics & Logs".
Tap "Export Log File" to share via AirDrop or Mail.
Average response time: < 24 hours from real Apple platform engineers.
