Yuan's Blog
EN 中

How to Develop a Local Video App with Tauri on macOS

When developing a Tauri desktop video application on macOS, you might intuitively assume that “video files” behave like images or text — that you can simply drop them into a <video> tag and play them. However, the request patterns, decoding process, and browser-level handling of video files are completely different — and filled with pitfalls.

Especially when using WebKit (Tauri’s default rendering engine) on macOS, the default asset:// protocol cannot handle videos that require Range requests, leading to silent errors such as “black screen,” “no sound,” or “failed to load.”

To help developers who have never worked with video applications avoid these issues, this article focuses on the request and transmission mechanisms of video files, analyzing common technical challenges and their solutions from multiple dimensions — format, codec, CORS, protocol, security, and player behavior.

Overview of Video Resource Requests and Transmission

Unlike images or text, videos in browsers are usually loaded via streaming. Streaming means data is downloaded and played at the same time, without waiting for the full file to finish downloading.

Basic Flow

  1. The browser initiates an HTTP request with a Range header, requesting only a portion of bytes (e.g., from 1MB onward).
  2. The server must respond with Accept-Ranges: bytes and the correct Content-Type: video/mp4.
  3. The browser receives the chunked data and demultiplexes it (splits audio/video/subtitle tracks).
  4. It then decodes each track and synchronizes playback of image, sound, and text.

⚠️ Tauri’s default asset:// protocol does not support Range requests or MIME recognition, which prevents the <video> element from retrieving the required data segments. This is the root cause of “black screen with sound” or total playback failure.

The following sections summarize the most frequent technical challenges developers face when building local video applications, based on the unique characteristics of video as a data type.

1. Browser Must Support Range Requests (Seeking/Streaming/Resuming)

  • When playing videos, browsers use Range requests by default to fetch partial content, enabling streaming, seeking, and resume playback.
  • If the protocol used (e.g., asset://) does not support Range requests, the video will fail to load or play properly.

2. Server Must Return Correct Response Headers (MIME Type and Accept-Ranges)

  • The server must respond with the correct content type (e.g., Content-Type: video/mp4).
  • Without Accept-Ranges: bytes, the browser cannot seek or resume playback.

3. Cross-Origin Resource Sharing (CORS) Limitations

  • If the video file is hosted on a different origin, the browser will block it unless Access-Control-Allow-Origin is explicitly set.
  • Even in local applications, fetching local files can be treated as a cross-origin request, leading to blocked resources.

4. Codec Format Must Be Supported by the Browser

  • Even if a video file loads successfully, it may fail to play if encoded with unsupported codecs (e.g., AC3 audio, HEVC video).
  • On macOS, Safari (WebKit) supports fewer audio/video codecs than Chromium.

5. Stricter Transmission Requirements

  • In desktop apps like Tauri or Electron, you cannot play large files directly via the asset:// protocol.
  • You must instead use valid file:// paths, Blob URLs, or define a custom protocol (e.g., stream://) that properly handles byte-range requests.

6. Common Track-Structure Pitfalls

  • Misaligned video/audio/subtitle tracks
  • Incompatible subtitle track formats
  • Multi-language audio/subtitle switching failures

By understanding the transmission characteristics of video data and how browsers handle Range requests, developers can design more robust playback architectures for local video applications on macOS using Tauri.