Video stutters or large files will not play from the NAS

Why playback over SMB stalls, what the Apple TV can decode on its own, and what to change.

Samba Oelek streams the file as bytes from the share and decodes it on the Apple TV. There is no transcoding and no server-side help. That makes two things matter: the network has to deliver the bitrate, and the Apple TV has to be able to decode the codec.

Network first

• A 4K HEVC travel film at 50 to 100 Mbit/s needs a solid link. Wired Ethernet on the Apple TV removes the most common cause of stalls. On Wi-Fi, use the 5 GHz band and keep the Apple TV close to the access point.
• Old NAS boxes and USB drives on routers can be too slow to serve high bitrates. Copy the file to a computer over the same link; if that copy is slow, the player will be too.
• SMB 3 is faster than SMB 2 on most servers. Allow SMB 3 in the server settings.

Then the codec

The Apple TV decodes H.264 and HEVC in hardware. ProRes, MPEG-4 Part 2 and Motion JPEG go through the app’s software decoder, which was tested with the combinations on the formats page. Very high bitrate ProRes variants may exceed what software decoding manages; that limit has not been measured. The ProRes recordings used in testing played from a Raspberry Pi share on an Apple TV 4K. If a file plays on a Mac but stutters on the Apple TV, the codec is the first suspect.

Large files

Files above 4 GiB, including 15 GB single-file holiday cuts, are supported. Seeking across the 4 GiB boundary was verified byte for byte. If a large file refuses to start, the cause is usually a codec the Apple TV cannot decode or a share that limits read sizes, not the file size.

What the app does not do

• It does not transcode, so it cannot make an unsupported codec play.
• It does not cache the whole file. Seeking reads from the new position.
• It does not select audio tracks. A file with an unusual audio codec may play without sound; see formats.

Checked against: Samba Oelek README, format tests and Raspberry Pi test matrix, 1.0.1. Last checked 2026-09-26.