copyparty icon indicating copy to clipboard operation
copyparty copied to clipboard

Add subtitle support for the web video player

Open xel-x opened this issue 4 months ago • 6 comments

Is your feature request related to a problem? Please describe.

When playing video files (like MP4s) that contain embedded subtitles, there is no way to view them. I understand this is a fundamental limitation of web browsers, which cannot render embedded subtitle streams directly from a video file.

Describe the solution you'd like

  1. Probe for Subtitles: When a video page is requested, use ffprobe or a similar tool to detect if and which subtitle tracks are embedded in the video file. Also search for [filename][.lang][.vtt/.srt], to find external files.

  2. Insert <track> Tags: For each detected subtitle track, dynamically generate and insert an HTML <track> tag into the <video> element. The src attribute for each tag should point to a unique URL that signals to extract that specific track (e.g., src=".../video.mp4?sub-track=1&format=vtt").

  3. On-Demand VTT Generation: When the browser requests one of these src URLs (i.e., when the user selects a subtitle), copyparty should use ffmpeg to extract only the requested subtitle track on-the-fly, convert it to the WebVTT (.vtt) format, and serve it directly to the browser. In case of external .srt file it could be converted using ffmpeg.

The generated HTML for the player could look something like this to make the subtitles available to the browser:

<video controls>
  <source src="my-video.mp4" type="video/mp4" />
  <track
    label="English"
    kind="subtitles"
    srclang="en"
    src="path/to/video.mp4?sub-track=0&format=vtt" />
  <track
    label="Deutsch"
    kind="subtitles"
    srclang="de"
    src="path/to/video.mp4?sub-track=1&format=vtt" />
</video>

Key Advantage: The primary benefit of this approach is the seamless user experience. The user doesn't have to manually create or manage extra subtitle files, which are, as standalone files, of no interest to them. Instead, subtitles are simply available in the browser where they are needed, reducing the manual preparation effort for a media library to zero, while still allowing for external subtitles if that's what the user already has.

Describe alternatives you've considered

I attempted a manual workaround by extracting the subtitles myself and placing the .vtt and .srt files in the same directory, using the same filename as the video (e.g., my-movie.mp4 and my-movie.vtt).

However, this approach does not work because these files do not automatically get detected and the required <track> tags in the HTML do not get generated. As a result, the browser is never made aware of the external subtitle files.

xel-x avatar Jul 30 '25 10:07 xel-x