starred/youtube-dl

Fork 0

mirror of https://github.com/ytdl-org/youtube-dl.git synced 2026-03-02 23:07:04 -05:00

Automatically embed subtitles in mkv files #4448

New issue

Closed

opened 2026-02-21 00:16:35 -05:00 by deekerman · 4 comments

deekerman commented

2026-02-21 00:16:35 -05:00

Owner

Originally created by @zJoul on GitHub (Apr 12, 2015).

Since it's possible to embed subtitles in mp4 (in a hard coded way probably), is there a way to embed subtitles files with mkvmerge or with ffmpeg in the post-processing option ?

(Maybe use the --exec command)

Originally created by @zJoul on GitHub (Apr 12, 2015). Since it's possible to embed subtitles in mp4 (in a hard coded way probably), is there a way to embed subtitles files with mkvmerge or with ffmpeg in the post-processing option ? (Maybe use the `--exec` command)

deekerman

2026-02-21 00:16:35 -05:00

closed this issue
added the
request

postprocessors
labels

deekerman commented

2026-02-21 00:16:38 -05:00

Author

Owner

@kphillisjr commented on GitHub (Nov 5, 2015):

This is an interesting idea, and to modify the program requires one to know the proper way to call mkvmerge.

# Example Invocation muxing streams into a specified file:
mkvmerge -o "MyMuxedVideo.mkv" videostream.mp4 --default-track 0 subtitle.enUS.ass subitle.esLA.ass subtitle.ptBR.ass
# Above example, but adding language Identifiers:
# NOTE: Language codes are based on ISO639-2
mkvmerge -o "MyMuxedVideo_withLanguages.mkv"  videostream.mp4 --default-track 0 \
   --language 0:en subtitle.enUS.ass  \
   --language 0:es subtitle.esLA.ass \
   --language 0:por subtitle.ptBR.ass

@kphillisjr commented on GitHub (Nov 5, 2015): This is an interesting idea, and to modify the program requires one to know the proper way to call mkvmerge. ``` sh # Example Invocation muxing streams into a specified file: mkvmerge -o "MyMuxedVideo.mkv" videostream.mp4 --default-track 0 subtitle.enUS.ass subitle.esLA.ass subtitle.ptBR.ass # Above example, but adding language Identifiers: # NOTE: Language codes are based on ISO639-2 mkvmerge -o "MyMuxedVideo_withLanguages.mkv" videostream.mp4 --default-track 0 \ --language 0:en subtitle.enUS.ass \ --language 0:es subtitle.esLA.ass \ --language 0:por subtitle.ptBR.ass ```

deekerman commented

2026-02-21 00:16:39 -05:00

Author

Owner

@kdeldycke commented on GitHub (Jun 6, 2017):

Isn't that one already supported via the --embed-subs option?

@kdeldycke commented on GitHub (Jun 6, 2017): Isn't that one already supported via the `--embed-subs` option?

deekerman commented

2026-02-21 00:16:39 -05:00

Author

Owner

@zJoul commented on GitHub (Jun 20, 2017):

I can't tell if at the time, the option was available, or at least available for mkv videos.

I did not dig in the source code, but maybe this option hardcode the subtitle into the video, altering the source. I wanted a way for softsubbing.

@zJoul commented on GitHub (Jun 20, 2017): I can't tell if at the time, the option was available, or at least available for mkv videos. I did not dig in the source code, but maybe this option hardcode the subtitle into the video, altering the source. I wanted a way for softsubbing.

deekerman commented

2026-02-21 00:16:39 -05:00

Author

Owner

@dirkf commented on GitHub (Sep 14, 2025):

Working in 2025, albeit clunky.

$ youtube-dl -v --write-sub --sub-lang cy --embed-sub -f 133+140 --merge-output-format mkv --user-agent 'Mozilla/5.0' '8047tcn3o5U'
[debug] System config: []
[debug] User config: []
[debug] Custom config: []
[debug] Command-line args: ['-v', '--write-sub', '--sub-lang', 'cy', '--embed-sub', '-f', '133+140', '--merge-output-format', 'mkv', '--user-agent', 'Mozilla/5.0', '8047tcn3o5U']
[debug] Encodings: locale UTF-8, fs utf-8, out utf-8, pref UTF-8
[debug] youtube-dl version 2025.05.05 [a084c80f7] (single file build)
[debug] ** This version was built from the latest master code at https://github.com/ytdl-org/youtube-dl.
[debug] ** For support, visit the main site.
[debug] Python 3.11.2 (CPython i686 32bit) - Linux-6.1.0-38-686-pae-i686-with-glibc2.36 - OpenSSL 3.0.17 1 Jul 2025 - glibc 2.36
[debug] exe versions: ffmpeg 5.1.7-0, ffprobe 5.1.7-0
[debug] Proxy map: {}
[youtube] 8047tcn3o5U: Downloading webpage
[youtube] 8047tcn3o5U: Downloading TVHTML5 API JSON
[debug] Loading youtube-nsig.b66835e2-main from cache
[debug] [youtube] Decrypted nsig a1fHd4TbPgrLKtXNj6zF => 4pkfOL5WExOYbA
[debug] [youtube] Decrypted nsig AlyXhewk1D-mkMCSJPVw => EYPKyqVnAVz8Ng
[info] Writing video subtitles to: Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.cy.vtt
[debug] Invoking downloader on 'https://rr2---sn-cu-aigss.googlevideo.com/videoplayback?expire=1757872993&ei=Aa_GaOjiF_2ahcIP0ZvBuAM&ip=46.208.6.89&id=o-AFtFOlv0EJy9XtWGgBaPnrO2PODIqznBs6DIVXeFjxzD&itag=133&aitags=133%2C134%2C135%2C136%2C137%2C160%2C242%2C243%2C244%2C247%2C248%2C271%2C278%2C313&source=youtube&requiressl=yes&xpc=EgVo2aDSNQ%3D%3D&met=1757851393%2C&mh=kd&mm=31%2C29&mn=sn-cu-aigss%2Csn-cu-c9i6&ms=au%2Crdu&mv=m&mvi=2&pl=25&rms=au%2Cau&initcwndbps=3600000&bui=AY1jyLNrOHpH07Fueao89lsaAIVKRHbyI_4SdjjTJMoc-pftjhU-Q5zjFJL7FHL0T268Gw493TIL6Dr3&vprv=1&svpuc=1&mime=video%2Fmp4&ns=f-_hUxJWxTpUi7DooPDHKfsQ&rqh=1&gir=yes&clen=19815621&dur=600.700&lmt=1699582418512430&mt=1757850842&fvip=2&keepalive=yes&lmw=1&fexp=51557447%2C51565115%2C51565682%2C51580970&c=TVHTML5&sefc=1&txp=6309224&n=EYPKyqVnAVz8Ng&sparams=expire%2Cei%2Cip%2Cid%2Caitags%2Csource%2Crequiressl%2Cxpc%2Cbui%2Cvprv%2Csvpuc%2Cmime%2Cns%2Crqh%2Cgir%2Cclen%2Cdur%2Clmt&sig=AJfQdSswRAIgDiAZTG2uZEk4GLgytyKz9SBRFdsRg44_jF_izMj_OxcCIAHgtUJ4DAcHqUjSsqKshkQmJj0LMea4JUn6brQRAYOc&lsparams=met%2Cmh%2Cmm%2Cmn%2Cms%2Cmv%2Cmvi%2Cpl%2Crms%2Cinitcwndbps&lsig=APaTxxMwRQIgZMJ4Q999O4q2B0cXu9kqEuJSvFYCAR7GCKb8qSaBZi8CIQDvt4Rf9n8TIZ3RN7PAWJHWaGQ_2FuIsg_m8ZukorC1WQ%3D%3D'
[dashsegments] Total fragments: 2
[download] Destination: Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mp4.f133.mp4
[download] 100% of 18.90MiB in 00:53
[debug] Invoking downloader on 'https://rr2---sn-cu-aigss.googlevideo.com/videoplayback?expire=1757872993&ei=Aa_GaOjiF_2ahcIP0ZvBuAM&ip=46.208.6.89&id=o-AFtFOlv0EJy9XtWGgBaPnrO2PODIqznBs6DIVXeFjxzD&itag=140&source=youtube&requiressl=yes&xpc=EgVo2aDSNQ%3D%3D&met=1757851393%2C&mh=kd&mm=31%2C29&mn=sn-cu-aigss%2Csn-cu-c9i6&ms=au%2Crdu&mv=m&mvi=2&pl=25&rms=au%2Cau&initcwndbps=3600000&bui=AY1jyLNrOHpH07Fueao89lsaAIVKRHbyI_4SdjjTJMoc-pftjhU-Q5zjFJL7FHL0T268Gw493TIL6Dr3&vprv=1&svpuc=1&mime=audio%2Fmp4&ns=f-_hUxJWxTpUi7DooPDHKfsQ&rqh=1&gir=yes&clen=9723174&dur=600.746&lmt=1699582657674312&mt=1757850842&fvip=2&keepalive=yes&lmw=1&fexp=51557447%2C51565115%2C51565682%2C51580970&c=TVHTML5&sefc=1&txp=6308224&n=EYPKyqVnAVz8Ng&sparams=expire%2Cei%2Cip%2Cid%2Citag%2Csource%2Crequiressl%2Cxpc%2Cbui%2Cvprv%2Csvpuc%2Cmime%2Cns%2Crqh%2Cgir%2Cclen%2Cdur%2Clmt&sig=AJfQdSswRQIhAOtjo3pJL4lsoQOF_wX4zqd7S64v29MwWVNGtGYIDP2mAiAjs4APpYieu0TqOYBEWimbG7q2AVHHkEdO5EsIJShsjw%3D%3D&lsparams=met%2Cmh%2Cmm%2Cmn%2Cms%2Cmv%2Cmvi%2Cpl%2Crms%2Cinitcwndbps&lsig=APaTxxMwRQIgZMJ4Q999O4q2B0cXu9kqEuJSvFYCAR7GCKb8qSaBZi8CIQDvt4Rf9n8TIZ3RN7PAWJHWaGQ_2FuIsg_m8ZukorC1WQ%3D%3D'
[dashsegments] Total fragments: 1
[download] Destination: Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.m4a.f140.m4a
[download] 100% of 9.27MiB in 00:21
[ffmpeg] Merging formats into "Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mkv"
[debug] ffmpeg command line: ffmpeg -y -loglevel repeat+info -i 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mp4.f133.mp4' -i 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.m4a.f140.m4a' -c copy -map 0:v:0 -map 1:a:0 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.temp.mkv'
Deleting original file Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mp4.f133.mp4 (pass -k to keep)
Deleting original file Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.m4a.f140.m4a (pass -k to keep)
[ffmpeg] Embedding subtitles in 'Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mkv'
[debug] ffmpeg command line: ffmpeg -y -loglevel repeat+info -i 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mkv' -i 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.cy.vtt' -map 0 -c copy -map -0:s -map -0:d -map 1:0 -metadata:s:s:0 language=cym 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.temp.mkv'
Deleting original file Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.cy.vtt (pass -k to keep)
$ ffprobe -hide_banner -show_programs 'Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mkv' 
Input #0, matroska,webm, from 'Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mkv':
  Metadata:
    MINOR_VERSION   : 0
    COMPATIBLE_BRANDS: iso6avc1mp41
    MAJOR_BRAND     : dash
    ENCODER         : Lavf59.27.100
  Duration: 00:10:00.75, start: 0.000000, bitrate: 393 kb/s
  Stream #0:0: Video: h264 (Main), yuv420p(tv, bt709, progressive), 426x240 [SAR 1:1 DAR 71:40], 29.97 fps, 29.97 tbr, 1k tbn (default)
    Metadata:
      HANDLER_NAME    : ISO Media file produced by Google Inc.
      VENDOR_ID       : [0][0][0][0]
      DURATION        : 00:10:00.700000000
  Stream #0:1(eng): Audio: aac (LC), 44100 Hz, stereo, fltp (default)
    Metadata:
      HANDLER_NAME    : ISO Media file produced by Google Inc.
      VENDOR_ID       : [0][0][0][0]
      DURATION        : 00:10:00.746000000
  Stream #0:2(cym): Subtitle: webvtt
    Metadata:
      DURATION        : 00:10:00.640000000
$

For a pre-combined format (no merge), try --recode-video mkv instead of --merge-output-format mkv.

@dirkf commented on GitHub (Sep 14, 2025): Working in 2025, albeit clunky. ```console $ youtube-dl -v --write-sub --sub-lang cy --embed-sub -f 133+140 --merge-output-format mkv --user-agent 'Mozilla/5.0' '8047tcn3o5U' [debug] System config: [] [debug] User config: [] [debug] Custom config: [] [debug] Command-line args: ['-v', '--write-sub', '--sub-lang', 'cy', '--embed-sub', '-f', '133+140', '--merge-output-format', 'mkv', '--user-agent', 'Mozilla/5.0', '8047tcn3o5U'] [debug] Encodings: locale UTF-8, fs utf-8, out utf-8, pref UTF-8 [debug] youtube-dl version 2025.05.05 [a084c80f7] (single file build) [debug] ** This version was built from the latest master code at https://github.com/ytdl-org/youtube-dl. [debug] ** For support, visit the main site. [debug] Python 3.11.2 (CPython i686 32bit) - Linux-6.1.0-38-686-pae-i686-with-glibc2.36 - OpenSSL 3.0.17 1 Jul 2025 - glibc 2.36 [debug] exe versions: ffmpeg 5.1.7-0, ffprobe 5.1.7-0 [debug] Proxy map: {} [youtube] 8047tcn3o5U: Downloading webpage [youtube] 8047tcn3o5U: Downloading TVHTML5 API JSON [debug] Loading youtube-nsig.b66835e2-main from cache [debug] [youtube] Decrypted nsig a1fHd4TbPgrLKtXNj6zF => 4pkfOL5WExOYbA [debug] [youtube] Decrypted nsig AlyXhewk1D-mkMCSJPVw => EYPKyqVnAVz8Ng [info] Writing video subtitles to: Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.cy.vtt [debug] Invoking downloader on 'https://rr2---sn-cu-aigss.googlevideo.com/videoplayback?expire=1757872993&ei=Aa_GaOjiF_2ahcIP0ZvBuAM&ip=46.208.6.89&id=o-AFtFOlv0EJy9XtWGgBaPnrO2PODIqznBs6DIVXeFjxzD&itag=133&aitags=133%2C134%2C135%2C136%2C137%2C160%2C242%2C243%2C244%2C247%2C248%2C271%2C278%2C313&source=youtube&requiressl=yes&xpc=EgVo2aDSNQ%3D%3D&met=1757851393%2C&mh=kd&mm=31%2C29&mn=sn-cu-aigss%2Csn-cu-c9i6&ms=au%2Crdu&mv=m&mvi=2&pl=25&rms=au%2Cau&initcwndbps=3600000&bui=AY1jyLNrOHpH07Fueao89lsaAIVKRHbyI_4SdjjTJMoc-pftjhU-Q5zjFJL7FHL0T268Gw493TIL6Dr3&vprv=1&svpuc=1&mime=video%2Fmp4&ns=f-_hUxJWxTpUi7DooPDHKfsQ&rqh=1&gir=yes&clen=19815621&dur=600.700&lmt=1699582418512430&mt=1757850842&fvip=2&keepalive=yes&lmw=1&fexp=51557447%2C51565115%2C51565682%2C51580970&c=TVHTML5&sefc=1&txp=6309224&n=EYPKyqVnAVz8Ng&sparams=expire%2Cei%2Cip%2Cid%2Caitags%2Csource%2Crequiressl%2Cxpc%2Cbui%2Cvprv%2Csvpuc%2Cmime%2Cns%2Crqh%2Cgir%2Cclen%2Cdur%2Clmt&sig=AJfQdSswRAIgDiAZTG2uZEk4GLgytyKz9SBRFdsRg44_jF_izMj_OxcCIAHgtUJ4DAcHqUjSsqKshkQmJj0LMea4JUn6brQRAYOc&lsparams=met%2Cmh%2Cmm%2Cmn%2Cms%2Cmv%2Cmvi%2Cpl%2Crms%2Cinitcwndbps&lsig=APaTxxMwRQIgZMJ4Q999O4q2B0cXu9kqEuJSvFYCAR7GCKb8qSaBZi8CIQDvt4Rf9n8TIZ3RN7PAWJHWaGQ_2FuIsg_m8ZukorC1WQ%3D%3D' [dashsegments] Total fragments: 2 [download] Destination: Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mp4.f133.mp4 [download] 100% of 18.90MiB in 00:53 [debug] Invoking downloader on 'https://rr2---sn-cu-aigss.googlevideo.com/videoplayback?expire=1757872993&ei=Aa_GaOjiF_2ahcIP0ZvBuAM&ip=46.208.6.89&id=o-AFtFOlv0EJy9XtWGgBaPnrO2PODIqznBs6DIVXeFjxzD&itag=140&source=youtube&requiressl=yes&xpc=EgVo2aDSNQ%3D%3D&met=1757851393%2C&mh=kd&mm=31%2C29&mn=sn-cu-aigss%2Csn-cu-c9i6&ms=au%2Crdu&mv=m&mvi=2&pl=25&rms=au%2Cau&initcwndbps=3600000&bui=AY1jyLNrOHpH07Fueao89lsaAIVKRHbyI_4SdjjTJMoc-pftjhU-Q5zjFJL7FHL0T268Gw493TIL6Dr3&vprv=1&svpuc=1&mime=audio%2Fmp4&ns=f-_hUxJWxTpUi7DooPDHKfsQ&rqh=1&gir=yes&clen=9723174&dur=600.746&lmt=1699582657674312&mt=1757850842&fvip=2&keepalive=yes&lmw=1&fexp=51557447%2C51565115%2C51565682%2C51580970&c=TVHTML5&sefc=1&txp=6308224&n=EYPKyqVnAVz8Ng&sparams=expire%2Cei%2Cip%2Cid%2Citag%2Csource%2Crequiressl%2Cxpc%2Cbui%2Cvprv%2Csvpuc%2Cmime%2Cns%2Crqh%2Cgir%2Cclen%2Cdur%2Clmt&sig=AJfQdSswRQIhAOtjo3pJL4lsoQOF_wX4zqd7S64v29MwWVNGtGYIDP2mAiAjs4APpYieu0TqOYBEWimbG7q2AVHHkEdO5EsIJShsjw%3D%3D&lsparams=met%2Cmh%2Cmm%2Cmn%2Cms%2Cmv%2Cmvi%2Cpl%2Crms%2Cinitcwndbps&lsig=APaTxxMwRQIgZMJ4Q999O4q2B0cXu9kqEuJSvFYCAR7GCKb8qSaBZi8CIQDvt4Rf9n8TIZ3RN7PAWJHWaGQ_2FuIsg_m8ZukorC1WQ%3D%3D' [dashsegments] Total fragments: 1 [download] Destination: Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.m4a.f140.m4a [download] 100% of 9.27MiB in 00:21 [ffmpeg] Merging formats into "Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mkv" [debug] ffmpeg command line: ffmpeg -y -loglevel repeat+info -i 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mp4.f133.mp4' -i 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.m4a.f140.m4a' -c copy -map 0:v:0 -map 1:a:0 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.temp.mkv' Deleting original file Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mp4.f133.mp4 (pass -k to keep) Deleting original file Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.m4a.f140.m4a (pass -k to keep) [ffmpeg] Embedding subtitles in 'Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mkv' [debug] ffmpeg command line: ffmpeg -y -loglevel repeat+info -i 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mkv' -i 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.cy.vtt' -map 0 -c copy -map -0:s -map -0:d -map 1:0 -metadata:s:s:0 language=cym 'file:Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.temp.mkv' Deleting original file Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.cy.vtt (pass -k to keep) $ ffprobe -hide_banner -show_programs 'Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mkv' Input #0, matroska,webm, from 'Enraizar - Acodo y Esquejes en Macetas-8047tcn3o5U.mkv': Metadata: MINOR_VERSION : 0 COMPATIBLE_BRANDS: iso6avc1mp41 MAJOR_BRAND : dash ENCODER : Lavf59.27.100 Duration: 00:10:00.75, start: 0.000000, bitrate: 393 kb/s Stream #0:0: Video: h264 (Main), yuv420p(tv, bt709, progressive), 426x240 [SAR 1:1 DAR 71:40], 29.97 fps, 29.97 tbr, 1k tbn (default) Metadata: HANDLER_NAME : ISO Media file produced by Google Inc. VENDOR_ID : [0][0][0][0] DURATION : 00:10:00.700000000 Stream #0:1(eng): Audio: aac (LC), 44100 Hz, stereo, fltp (default) Metadata: HANDLER_NAME : ISO Media file produced by Google Inc. VENDOR_ID : [0][0][0][0] DURATION : 00:10:00.746000000 Stream #0:2(cym): Subtitle: webvtt Metadata: DURATION : 00:10:00.640000000 $ ``` For a pre-combined format (no merge), try `--recode-video mkv` instead of `--merge-output-format mkv`.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/youtube-dl#4448

No description provided.

Rows
Columns