I am trying to embed a thumbnail in a .mkv file with h265 video encoding using ffmpeg from the Linux command line. I am able to embed thumbnails in h264-encoded .mp4 files using the following command:

ffmpeg -i video-in.mp4 -i thumb.png -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4

However, a similar command substituting .mkv files does not correctly embed the thumbnail:

ffmpeg -i video-in.mkv -i thumb.png -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mkv

ffmpeg will run just fine, throwing no warnings or errors, but the thumbnail that shows in Dolphin after it's run its course is a generic auto-generated thumbnail instead of the one I specified with -i thumb.png.

I first learned how to do this while reading the ffmpeg documentation here (a bit further down, where it explains dispositions). I noticed that it says "Not all muxers support embedded thumbnails, and those who do, only support a few formats, like JPEG or PNG." This makes me think that maybe the matroska/mkv muxer simply doesn't support embedded thumbnails. However, further research has me confused.

The ffmpeg Formats documentation doesn't list thumbnail(s) as an option in the metadata section of the matroska muxer docs, which further supports the theory that embedding is impossible. I figured I'd double-check that thumbnails are listed as an option for mp4s just to be sure. However, the mov/mp4/ismv muxer section doesn't even have a Metadata sub-section.

The MP4 File Format Documentation I've been able to find isn't very helpful. I can't tell whether thumbnail embedding is possible based on this documentation alone (though obviously I know from experience that it's possible).

The MKV Container Documentation is a lot more thorough, though, and it says in the first section ("What is an MKV File?") that "MKV also supports descriptions, ratings, cover art, and even chapter points" (emphasis mine). In the "Matroska Structure" section it also lists "Attachments" as one of the top-level elements of the container structure. All of this leads me to believe that embedded thumbnails are in fact possible with .mkv files.

So, to summarize: on the one hand, ffmpeg's documentation makes me think I can't embed thumbnails in .mkv files. But the MKV file format documentation makes me think I should be able to. I haven't been able to figure out for sure either way, though, and even if it is possible, the method for doing so differs from the method I use for .mp4 files.

Is it possible to embed thumbnails in .mkv files? If so, how would I do it (preferably using ffmpeg on Linux)?

1 Answer 1


I was also going down this rabbit hole and found that there's an option -attach filename that's more specific to mkv files. It's at the end of the "Main Options" section of the manual: https://ffmpeg.org/ffmpeg.html#Main-options

ffmpeg -i video.mkv -attach cover.jpg -metadata:s:t:0 mimetype=image/jpeg -c copy out.mkv

The -metadata:s:t:0 specifically selects the first attachment stream (which should be just the cover photo).

  • 1
    This works but I still would like to remind that the thumbnail image must have "cover" as its file name, such as "cover.jpg" or "cover.png". If we use file names like "thumb.png", FFmpeg won't report an error, but the thumbnail also won't display properly on the MKV output.
    – wklchris
    Commented Oct 6, 2023 at 5:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.