Skip to main content

Adaptive streaming (hls) with subtitles linked in the m3u8 playlist, is it achievable?



  • Stephen Doyle


    Currently, the m3u8 playlists we create when using adaptive bitrate streaming do not include the option of adding a subtitle file to the playlist automatically.

    Depending on what you need, a possible workaround is to create your own .m3u8 playlist, referencing the .ts files already created by us, and then upload that playlist and use it when delivering the video to players that can't have the subtitles sent as separate configuration.

    For example, you could:

    • Download the m3u8 file for the video, or for one representation of the video, depending on what you need
    • Edit that m3u8 to add a reference to the subtitle file
    • Also edit the URL for each of the EXT-X-STREAM-INF entries to be absolute instead of relative (see note below)
    • Re-upload that m3u8 file back to the account, with `resource_type: raw`
    • Use that new m3u8 URL to deliver the video to the player

    (The URLs need to be updated because the delivery path of a raw file will begin with /raw/upload... but the videos need to be accessed via /video/upload, so it won't match if you're using the relative paths we add to the playlist by default)

    We do also have a feature request to add direct support for us creating an m3u8 with subtitles , and it may be added as a new feature in the future but I'm afraid I don't know when that may be.

    Another option may be to use our 'subtitle' transformation which takes an SRT or VTT file and overlays it onto the video, so it will be present in the actual video frames, and will be seen by all viewers:



  • DevOps Triggerz

    Thank you very much for a very thorough rely Stephen! Really well described 🥇

  • Stephen Doyle

    You're very welcome; please let me know if there's anything else we can help with, and you can also contact our support team directly via the "Submit a request" link on the top of this support site

  • DevOps Triggerz

    Thanks again, and yes there might be.

    I have tried manually constructing the m3u8 file like you described, and by following this article:

    When I run it on my local machine with VLC it actually streams the video nicely, so I think the absolute path part is done correctly. I'm not too sure if I am referencing the subtitle correctly though, because I can't choose subtitles in VLC still, but that could also be because VLC might not support it. Or maybe it's not possible at all referencing vtt subtiltles in hls manifest and need to be a different subtitle format, that's not 100% clear to me.

    Anyway. I'm not allowed to upload the file to cloudinary (at least from the dashboard), it responds with "invalid file" I am not sure if that is because the dasoboard upload is always expecting an actual media file? In which case I need to find a way to upload it using the API so I can specify that it should be resource_type: raw, as you mention? or, it might be because my files is constructed wrong, and cloudinary detects it.

    Would you mind taking a look at this manifest and see if you can spot something obviously wrong?

  • Victor Li

    Hi there,

    Just to clarify, your issue is two-fold?

    1) The new .m3u8 file you constructed plays in VLC locally but not with subtitles, and

    2) You are receiving an "invalid file" error when uploading the new .m3u8 file through our UI to your account?

    Could you try uploading the files via our Upload API with `resource_type: raw` or alternatively, open a ticket with us and attach them so that we can take a look at both issues on our end? 


  • DevOps Triggerz

    Hi Victor.

    I have now written an application and uploaded the m3u8 file successfully via the API.


    However, I think my handcrafted m3u8 playlist (pasted above) is constructed with fault, as I do not see subtitles when I play the stream. If you prefer me to open a ticket I will do that.

    Regards, Rasmus

  • Stephen Doyle

    Hi Rasmus,

    The format of your m3u8 file looks OK to me, and the video plays for me from this m3u8, but I also don't see the subtitles, as you say. I checked this in VLC, though, and I'm not sure 100% sure if VLC certainly supports this; it did appear to load the .vtt file from Cloudinary, but I didn't see any errors or warnings, it just didn't render anything

    In which player were you checking, and did you see the player suggest that subtitles were available? were any errors thrown?

    Regarding the other error that you mentioned, it's not currently possible to force the resource type to 'raw' when uploading via Media Library: you'll need to use the API to upload the .m3u8 if you don't want us to try and auto-detect the format (which will fail in this case because we treat .m3u8 as a video format)



Post is closed for comments.