How to set custom handler_name metadata for subtitle stream using FFMPEG

Question

I'm currently using FFMPEG to embed subtitles into my MP4 files and I am stumped trying to figure out how to custom set the "handler_name" metadata tag on my subtitle stream so I can control the name that is displayed when selecting the subtitle within a player like MPC-HC (Media Player Classic)?

My current command to embed the subtitle is:

ffmpeg -i "video.mp4" -sub_charenc UTF-8 -i "video.srt" -c:v copy -c:a copy -c:s mov_text -metadata:s:s:0 language=eng -metadata:s:s:0 handler_name="English" -id3v2_version 3 -write_id3v1 1 "subbed_video.mp4"

Output:

C:\path\to>ffmpeg -y -i "video.mp4" -sub_charenc UTF-8 -i "video.srt" -c:v copy -c:a copy -c:s mov_text -metadata:s:s:0 language="eng" -metadata:s:s:0 handler_name="English" -id3v2_version 3 -write_id3v1 1 "subbed_video.mp4"
ffmpeg version N-68482-g92a596f Copyright (c) 2000-2014 the FFmpeg developers
  built on Dec 16 2014 02:53:08 with gcc 4.9.2 (GCC)
  configuration: --enable-gpl --enable-version3 --disable-w32threads --enable-avisynth --enable-bzlib --enable-fontconfig --enable-frei0r --enable-gnutls --enable-iconv --enable-libass --enable-libbluray --enable-libbs2b --enable-libcaca --enable-libfreetype --enable-libgme --enable-libgsm --enable
  libavutil      54. 15.100 / 54. 15.100
  libavcodec     56. 15.100 / 56. 15.100
  libavformat    56. 15.105 / 56. 15.105
  libavdevice    56.  3.100 / 56.  3.100
  libavfilter     5.  3.101 /  5.  3.101
  libswscale      3.  1.101 /  3.  1.101
  libswresample   1.  1.100 /  1.  1.100
  libpostproc    53.  3.100 / 53.  3.100
Input #0, mov,mp4,m4a,3gp,3g2,mj2, from 'video.mp4':
  Metadata:
    major_brand     : isom
    minor_version   : 512
    compatible_brands: isomiso2avc1mp41
    encoder         : Lavf55.34.101
  Duration: 01:27:44.17, start: 0.000000, bitrate: 878 kb/s
    Stream #0:0(und): Video: h264 (High) (avc1 / 0x31637661), yuv420p, 1280x536 [SAR 1:1 DAR 160:67], 842 kb/s, 24 fps, 24 tbr, 12288 tbn, 48 tbc (default)
    Metadata:
      handler_name    : VideoHandler
    Stream #0:1(und): Audio: aac (HE-AAC) (mp4a / 0x6134706D), 48000 Hz, stereo, fltp, 32 kb/s (default)
    Metadata:
      handler_name    : SoundHandler
    Stream #0:2(eng): Subtitle: mov_text (tx3g / 0x67337874), 0 kb/s (default)
    Metadata:
      handler_name    : SubtitleHandler
Input #1, srt, from 'video.srt':
  Duration: N/A, bitrate: N/A
    Stream #1:0: Subtitle: subrip
Output #0, mp4, to 'subbed_video.mp4':
  Metadata:
    major_brand     : isom
    minor_version   : 512
    compatible_brands: isomiso2avc1mp41
    encoder         : Lavf56.15.105
    Stream #0:0(und): Video: h264 ([33][0][0][0] / 0x0021), yuv420p, 1280x536 [SAR 1:1 DAR 160:67], q=2-31, 842 kb/s, 24 fps, 24 tbr, 12288 tbn, 12288 tbc (default)
    Metadata:
      handler_name    : VideoHandler
    Stream #0:1(und): Audio: aac ([64][0][0][0] / 0x0040), 48000 Hz, stereo, 32 kb/s (default)
    Metadata:
      handler_name    : SoundHandler
    Stream #0:2(eng): Subtitle: mov_text ([8][0][0][0] / 0x0008) (default)
    Metadata:
      handler_name    : English
      encoder         : Lavc56.15.100 mov_text
Stream mapping:
  Stream #0:0 -> #0:0 (copy)
  Stream #0:1 -> #0:1 (copy)
  Stream #0:2 -> #0:2 (mov_text (native) -> mov_text (native))
Press [q] to stop, [?] for help
frame=126337 fps=13751 q=-1.0 Lsize=  564499kB time=01:27:44.17 bitrate= 878.5kbits/s
video:541239kB audio:20564kB subtitle:39kB other streams:0kB global headers:0kB muxing overhead: 0.472881%

The command completes sucessfully, but when I run:

ffmpeg -i "C:\path\to\subbed_video.mp4"

it shows:

Stream #0:2(eng): Subtitle: mov_text (tx3g / 0x67337874), 0 kb/s (default)
Metadata:
  handler_name    : SubtitleHandler

Even though the output from the command shows:

Stream #0:2(eng): Subtitle: mov_text ([8][0][0][0] / 0x0008) (default)
Metadata:
  handler_name    : English
  encoder         : Lavc56.15.100 mov_text

No matter what options I have tried or what order I place the -metadata tags in, this tag simply will not set with FFMPEG? I find it really ugly to see SubtitleHandler [eng] (tx3g) (English) within my player's menu instead of simply saying English.

Now, I can work around this issue by using MP4BOX to embed the subtitles into my mp4's using:

MP4BOX -lang eng -add "video.srt:name=English" "video.mp4" -out "subbed_video.mp4"

Adding "name=English" allows me to set the subtitle stream's "handler_name" to "English"; which displays perfectly in FFMPEG and MPC-HC, but the problem is that I do not want my app to be dependent on an additional external tool like MP4BOX if it can be avoided?

I would greatly appreciate any advice regarding how to properly set the "handler_name" tag on my subtitle stream using FFMPEG, or maybe a confirmation as to whether FFMPEG can even handle this tag seeing as it is not technically listed in FFMPEG's valid metadata tag list?

P.S. As an alternative to FFMPEG, I would be willing to use AtomicParsley to set the "handler_name" as I will already be using it to set advanced metadata on the "subbed_video.mp4" after I embed the subtitles. It does seem like it would be possible to do with AtomicParsley, but I have not been able to understand half the help information with regards to setting custom ATOM's.

TIA!!

Borden

I should also mention that this was tested with the latest 64-bit build (git-92a596f (2014-12-16)) from here: ffmpeg.zeranoe.com/builds – Borden

Answer 1

Finally figured it out today, and I cannot believe I didn't try this before...Although the tag name is listed as handler_name= in FFMPEG's output, the active tag to use is just handler=, without adding _name.

-metadata:s:s:0 handler="English"

ffmpeg -i "video.mp4" -sub_charenc UTF-8 -i "video.srt" -c:v copy -c:a copy -c:s mov_text -metadata:s:s:0 language=eng -metadata:s:s:0 handler="English" -id3v2_version 3 -write_id3v1 1 "subbed_video.mp4"

Borden

You can also use the below to change the name that is displayed for the audio channels: (assuming file has two audio streams, Stereo and Surround 5.1) -metadata:s:a:0 handler="English (Stereo)" -metadata:s:a:1 handler="English (Surround 5.1)" – Borden

is there a way to delete this handler_name tag completely? I left it blank but that didn't do it, I used -1 and nothing. – Necroscopy

Where did you find that the name of the tag is handler? Is there a list of these tag names with their meanings? I am searching for a way to add "media created" time, but yet unable to find the correct tag name... – Arabele

@Felipe, blank would most likely lead to default settings, -1 would most likely be interpreted as a strin. Best i could auggest is try using a space or tab..? – Borden

@anishsane, tbh i guessed it after hours upon hours of searching! Lol. I'm not too sure how to manually set the creation date as the creation date should be set upon the creation of the file and afaik would not be able to be manually set? – Borden

No, there is a "media created" field shown in windows explorer. (Not sure if it is applicable for mp4) "file created" is different than this. Basically, I have multiple episodes of a TV series and I want to somehow encode the episode release date in the file. So far, I have used "comment" field for this; but that is not available for .mkv it seems. I was hoping that there should be a common field across media file types for this. – Arabele

@Arabele FFmpeg's Matroska muxer honors the following metadata keys: "title", "description", "language". Beyond these keys, the Matroska muxer also accepts free-form key/value metadata pairs. For example: ffmpeg -y -i input.mkv -codec copy -metadata comment="Matroska also accepts free-form key/value pairs" -metadata foo="bar" -metadata description="Matroska description" -metadata:s:v:0 title="Video stream title/description" -metadata:s:a:0 title="Audio stream title/description" -metadata:s:s:0 language=eng -metadata:s:s:0 title="Subtitle stream title/description" output.mkv – Devonna

It seems that the answer is obsoleted, with FFmpeg version git-2019-11-15-bfa8272 handler="English" doesn't work for me while handler_name="English" worked. – Sandstone

Answer 2

If you're using VLC and the accepted answer didn't work, you should add the title option to your stream metadata. Using OPs example:

ffmpeg -i "video.mp4" -sub_charenc UTF-8 -i "video.srt" -c:v copy -c:a copy -c:s mov_text -metadata:s:s:0 language=eng -metadata:s:s:0 title="English" -id3v2_version 3 -write_id3v1 1 "subbed_video.mp4"

Same goes for other streams. Tested on FFmpeg version N-79630-g9ac154d.

Gilberte

Answer 3

I've had no luck setting the label for subtitle (or audio) streams using ffmpeg, at least not in a way that players show. After a ton of research, it seems that what vlc and other players show for the stream labels isn't based on the handler at all, but is based on the UDTA name atom in the mp4/QuickTime metadata.

The only tool I've been able to find that will reliably set the UDTA name in a way that is shown by VLC and other players without re-encoding or adding a new stream has been GPAC/mp4box, and this is only a very recently added (in Oct 2020) feature:

MP4Box -udta TRACKID:type=name:str="Track Label" file.mp4 

Ennead