TECHNICAL KNOWLEDGE BASE & PLAYBACK DIAGNOSTICS

Engineering Support & Playback Architecture

Practical setup guides, format compatibility references, audio pipeline explanations, and diagnostic instructions for Apple TV 4K, Mac, iPhone, and iPad.

1. Video & Apple TV 4K 2. Audio & Passthrough 3. Network & Storage 4. Subtitle Engines 5. iCloud Sync 6. Diagnostics & Contact
1

Apple TV 4K Video Timing & Frame Rate Matching

Eliminating judder, configuring dynamic range, and understanding video decode pathways.

Match Frame Rate & Match Dynamic Range

For cinematic 24.000 fps and 23.976 fps film playback, we recommend enabling both Match Frame Rate and Match Dynamic Range in your Apple TV settings:

Apple TV Settings > Video and Audio > Match Content > Enable "Match Dynamic Range" & "Match Frame Rate"

When enabled, tvOS switches HDMI display timing to match the exact source cadence of your file, eliminating 3:2 pulldown stutter and ensuring proper HDR tone-mapping on OLED and high-end displays.

Dolby Vision Profiles (P5 & P8.1)

Velis routes MP4 and MOV streams with Dolby Vision Profile 5 (streaming single-layer) and Profile 8.1 (cross-compatible with HDR10 fallback) through Apple's native VideoToolbox hardware pipeline on Apple TV 4K.

Profile 7 Disc Rips (MEL/FEL): Apple tvOS does not provide access to secondary enhancement video streams required for full Profile 7 Full Enhancement Layer (FEL) reconstruction. For Profile 7 titles, Velis plays the primary HDR10 10-bit video track with standard dynamic metadata.

Container Routing Architecture

Velis dynamically selects the optimal decoding pipeline based on media container and codec:

  • AVFoundation: MP4, MOV, and M3U8 (HLS) streams are routed directly to native Apple hardware decoders for zero overhead and minimal thermal impact.
  • VLCKit / KSPlayer: MKV, AVI, and WebM containers are demuxed via high-performance native engines with hardware-accelerated video decoding enabled wherever supported.
2

Audio Pipeline, Lossless Decoding & eARC

Understanding tvOS audio architecture, TrueHD software decode, and spatial sound.

Lossless Dolby TrueHD & DTS-HD MA → Multichannel LPCM

Because tvOS and macOS do not permit third-party applications to output raw Dolby TrueHD or DTS-HD MA bitstream over HDMI, Velis software-decodes these tracks directly on-device using VLCKit.

The decoded audio is transmitted losslessly as uncompressed multichannel Linear PCM (up to 7.1 channels, 48kHz / 96kHz, 24-bit) over HDMI eARC to your AV receiver or soundbar. This preserves 100% of the original audio quality with zero generational compression.

Note on Dolby Atmos: Bitstream TrueHD Atmos spatial metadata cannot be passed through Apple tvOS HDMI output. Standard Dolby Digital Plus (E-AC-3) Atmos tracks from streaming providers are handled via native tvOS system audio.

Spatial Audio & Dynamic Head Tracking

When using compatible Apple audio hardware (AirPods Pro, AirPods Max, AirPods 3/4), Velis feeds multichannel surround channels into Apple's Spatial Audio rendering engine with real-time head orientation tracking.

Lip-Sync & Audio Delay Offset

If your display or soundbar introduces processing latency, you can adjust audio timing during playback via the audio track menu in +/- 50ms increments to achieve frame-perfect synchronization.

3

Network Performance, Media Servers & Buffering

High-bitrate 4K streaming setup, server endpoints, and local file access.

High-Bitrate 4K REMUX Recommendations

4K UHD Blu-ray REMUX files frequently burst above 90–120 Mbps. To ensure stutter-free streaming:

  • Use a wired Gigabit Ethernet connection on Apple TV 4K where available.
  • For Wi-Fi, connect to a 5GHz or 6GHz channel (Wi-Fi 6 / 802.11ax) located near the device.
  • Verify your local media server storage is capable of sustained read speeds above 25 MB/s.

Media Server Connections

Velis integrates natively via official REST APIs with zero custom plugins required on your server:

  • Plex: Connect using your Plex account or manual server IP:port. Ensure "Direct Play" is enabled in server streaming quality settings.
  • Jellyfin & Emby: Connect directly via server URL and API credentials. If using a reverse proxy (Caddy, Nginx, Cloudflare Tunnel), ensure WebSocket connections and large headers are permitted.
  • WebDAV / Nextcloud: Add custom WebDAV endpoints using HTTPS for encrypted streaming.

Local File Importing & OS-Mounted Shares (Mac & iOS)

On macOS, iOS, and iPadOS, Velis features direct file importing using the native Apple system file picker (`.fileImporter`). You can grant security-scoped access to:

  • Local Mac storage folders and external USB-C / Thunderbolt solid-state drives.
  • Network shares mounted through your operating system (e.g. macOS Finder connected via `smb://` or iOS Files app network connections).

tvOS Note: Apple TV does not provide a local file browser or USB file access; all media on tvOS is accessed over your local network.

4

Subtitle Customization & Rendering Engines

Text subtitle customization, bitmap formats, and chapter skipping.

Text Subtitle Customization (SRT, VTT, ASS)

Velis provides comprehensive styling controls for text-based subtitle tracks:

  • Typography: Choose from system fonts (San Francisco, SF Pro, SF Mono, Georgia, etc.).
  • Size & Weight: Scale text from compact to cinema-large with proportional display scaling.
  • Contrast & Legibility: Configure text color and background box opacity to ensure readability over bright scenes.

Authored Bitmap Subtitles (PGS & VobSub)

Blu-ray PGS (`.sup`) and DVD VobSub (`.sub`/`.idx`) are image-based formats mastered directly onto physical discs. Because they consist of pre-rendered graphics rather than text characters:

  • They render with their exact original authored fonts, glyphs, and screen positioning.
  • Font family, size, and color customization controls do not apply to bitmap subtitles.

Smart Intro & Credits Skipping

When chapter metadata or media server markers (Plex / Jellyfin intro markers) are present in the stream, Velis surfaces an on-screen skip button to leap past opening theme sequences and end credits with a single tap.

5

iCloud Synchronization & Viewing Profiles

Multi-device continuity, private CloudKit storage, and sync troubleshooting.

Two-Tier Sync Architecture

Velis uses two distinct Apple cloud technologies designed to balance speed and privacy:

  • iCloud Key-Value Store (KVS): Syncs lightweight playback progress timestamps across devices in near-real-time.
  • Private CloudKit Container: Syncs your library favorites, custom playlists, and watch history records. Stored in your private Apple iCloud account (`iCloud.com.unkit.velis`); developers have zero access.

Separate Viewing Profiles

Velis supports creating distinct viewing profiles so household members can keep their watch histories, favorites, and resume progress independent from one another.

Important Notice: Profiles are designed for personal library organization. They do not enforce PIN-locked parental controls or content-rating restrictions.

Troubleshooting Sync Stalls

If playback position or favorites are not synchronizing between your Apple devices:

  • Verify all devices are signed into the exact same Apple ID in system settings.
  • Ensure iCloud Drive is enabled: Settings > [Your Name] > iCloud > iCloud Drive > On.
  • Check if Low Power Mode is active on iPhone or iPad; iOS pauses background cloud synchronization while in power saving mode.
  • Disabling Sync: Toggling iCloud sync off in settings stops future synchronization on that device; existing cloud records remain until cleared via the in-app "Purge All Data" reset.
6

Playback Diagnostics & Developer Support

HUD metrics, anonymized log export, open source notices, and contact info.

Real-Time Technical Playback HUD

Velis includes an on-screen technical heads-up display accessible during playback. The HUD displays active video decode engine (VideoToolbox vs VLCKit), container format, video bitrate, dropped frame counter, audio format, and channel allocation.

Exporting Anonymous Diagnostic Logs

When diagnosing playback or networking issues, you can generate an anonymized diagnostic report from within the app:

Velis Settings > Advanced > Export Diagnostic Log

All private server hostnames, media titles, and authentication tokens are automatically sanitized and stripped before export.

Open Source Licenses & LGPL Release

Velis includes software licensed under the GNU Lesser General Public License (LGPL v2.1), including VLCKit. In compliance with LGPL requirements, the corresponding source code release and build instructions are publicly available at:

https://github.com/unkitd/Velis/releases/tag/v1.0.0-lgpl

Direct Developer Support

Have a playback question, bug report, or network setup issue?

Email support@velisapp.com