mirror of
https://github.com/CCExtractor/ccextractor.git
synced 2026-02-03 21:23:48 +00:00
[Proposal] Adding an option to enable/disable X-TIMESTAMP-MAP in WebVTT #523
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @ozt860071 on GitHub (Nov 22, 2019).
Please prefix your issue with one of the following: [BUG], [PROPOSAL], [QUESTION].
CCExtractor version (using the --version parameter preferably) : X.X
In raising this issue, I confirm the following (please check boxes, eg [X] - and delete unchecked ones):
My familiarity with the project is as follows (check one, eg [X] - and delete unchecked ones):
Necessary information
-out=webvttVideo links (replace text below with your links)
Additional information
Currently when WebVTT is specified as output, X-TIMESTAMP-MAP is automatically added. And if no subtitle text is found in the input, it generates an empty WebVTT, with just one line "WEBVTT" in the file.
There are potentially two issues with this implementation.
(a) X-TIMESTAMP-MAP is not a WebVTT requirement, but Apple HLS requirement, this may cause a problem if it is used in non-HLS environment. It should be an option to turn it off.
(b) On the other hand, Apple HLS spec says "an X-TIMESTAMP-MAP metadata header SHOULD be added to each WebVTT header", which includes the empty ones. The spec also says "If a WebVTT segment does not have the X-TIMESTAMP-MAP, the client MUST assume that the WebVTT cue time of 0 maps to an MPEG-2 timestamp of 0.". But unfortunately, not all clients follow this rule. It is safer to add X-TIMESTAMP-MAP in all VTT files, if it is enabled.
So, my proposal is to add an option for WebVTT, whether X-TIMESTAMP-MAP is enabled or disabled. And if it is enabled, it will be added in every VTT file it generates, including one with no caption cues.
(cf. "HTTP Live Streaming": https://tools.ietf.org/html/rfc8216 section 3.5)
@NilsIrl commented on GitHub (Dec 4, 2019):
What happens if
X-TIMESTAMP-MAPis disabled and the WebVTT cue time 0 doesn't map to an MPEG-2 timestamp of 0?@NilsIrl commented on GitHub (Dec 4, 2019):
What would be the reason to not have the
X-TIMESTAMP-MAP?@NilsIrl commented on GitHub (Dec 4, 2019):
Wouldn't it be better to have the
X-TIMESTAMP-MAPheader present all the time?@ozt860071 commented on GitHub (Dec 5, 2019):
You’ll lose caption, and in worst case, video freeze.
@ozt860071 commented on GitHub (Dec 5, 2019):
Since it is HLS requirement, this may affect negatively in non-HLS use cases. I hope not.
I don’t mind having it all the time, though.
@ozt860071 commented on GitHub (Dec 5, 2019):
I am fine with this. But I don’t know how it affects in other use cases where this is not required.
Thanks
@NilsIrl commented on GitHub (Dec 5, 2019):
@cfsmp3 What should I do? I feel like the best here is to always use
X-TIMESTAMP-MAP.@NilsIrl commented on GitHub (Dec 5, 2019):
There is also the general problem that
ccextractorcreates files even when it can't find anything making this problem more general and not limited to.vtt. @cfsmp3@ozt860071 commented on GitHub (Dec 5, 2019):
But for HLS at least, I need an output even if no caption text is contained in the .vtt file. The client needs the get the timing info from X-TIMESTAMP-MAP for synchronization.
Thanks
@NilsIrl commented on GitHub (Dec 5, 2019):
why would you need to synchronize if you don't have subtitles?
@cfsmp3 commented on GitHub (Dec 6, 2019):
It's part of the HLS specification. If there are subtitles in WebVTT:
Subtitles
5.1. Subtitles MAY be provided.
5.2. Subtitles MUST be WebVTT (according to the HLS specification) or IMSC1 in fMP4.
5.3. WebVTT subtitles MUST be in text files, with an X-TIMESTAMP-MAP according to the HLS specification.
References:
https://developer.apple.com/documentation/http_live_streaming/hls_authoring_specification_for_apple_devices
https://tools.ietf.org/html/rfc8216#page-13
Note that Apple there says MUST (in 5.2) but the RPC8216 says SHOULD.
But still, if we generate a .vtt file, even if it has no subtitles, it should have the required header. Otherwise players may refuse to play anything at all.
@NilsIrl commented on GitHub (Dec 6, 2019):
The thing is that you can't synchronize between 2 things when you're missing 1 of the 2, in this case subtitles.
@cfsmp3 commented on GitHub (Dec 6, 2019):
An empty subtitle file is not the same as no subtitle file. If there's a subtitle file even if it has no actual subtitles inside you need to be able to know where it starts relative to the video.
In any case if the specs say that's the way it is then that's what we have to implement, unless you want to get in touch (you can) with the RFC8216 writers and discuss :-)
Otherwise we're just not standard compliant and that's not a good thing to be. In fact, if you read the RFC you will see that in a bunch of places it says that clients MUST refuse to play media that is not compliant. Not that they should do their best to play it anyway, but the opposite.
And well, there's a good reason for that: To force all programs generating media to follow the specs.
@NilsIrl commented on GitHub (Jan 12, 2020):
@cfsmp3 commented on GitHub (Jan 12, 2020):
You want to sync using time, not bytes. There's some reasons for this, one of them being that you might be starting the stream in the middle and not have access to anything before you started playing - for example, when you turn on your TV your TV needs to start playing the stream from the point you turn it on, Also, the stream never ends...
Second, even if we were talking about actual files with a beginning and an end, they will contain at the very least 1 video track and 1 audio track (possibly more of audio), so what byte offset would you use?
@NilsIrl commented on GitHub (Jan 12, 2020):
In case 1, the value would just be metadata that would kinda be useless without the exact same video file.
For example in the East Enders file here is the header:
MPEGTS is the duration since the start of the stream (before the start of the video file)?
@cfsmp3 commented on GitHub (Jan 12, 2020):
Not exactly. The MPEGTS is a clock that runs at 90,000 Hz and that rolls
over roughly every 26 hours. Forget about the "start of the stream", for
all purposes assume the stream doesn't have a beginning or an end, it's
24x7 (assuming we're talking about a TV channel). You need to sync the
audio, video and packets. Of course packets interleaved in a way that they
are playable without having a huge buffer (which would also cause a delay,
and for example when watching sports you want the less possible latency),
but still you need to sync everything.
.srt and other video formats do start at 00:00 assuming that you are going
to attach them to a file that also starts at 00:00. That's fine, we love
.srt and CCExtractor produces timing relative to the start of a file :-)
But professional use, in broadcast media, is just different.
If someone from a media company tells us they need the MPEG clock to sync,
they're probably know what they are doing.
On Sun, Jan 12, 2020 at 1:28 PM Nils ANDRÉ-CHANG notifications@github.com
wrote:
@kdrag0n commented on GitHub (Jan 21, 2020):
Shouldn't this issue be closed since #1176 has been merged?
@NilsIrl commented on GitHub (Jan 21, 2020):
Well the underlying issue is still present so it doesn't solve the original problem
(THE header doesn't show up all the time). I'm going to reopen my PR
@NilsIrl commented on GitHub (Jan 22, 2020):
Is there a file I can test it with? (a file without subtitles).
@cfsmp3 commented on GitHub (Jan 25, 2020):
You can use any file - just manually select --datapid pointing to a PID that is not present in the stream.
@NilsIrl commented on GitHub (Feb 15, 2020):
This shouldn't affect the header right?
@NilsIrl commented on GitHub (Feb 15, 2020):
db646f50ac/src/lib_ccx/general_loop.c (L991-L1006)If you look at the above snippet,
data_node == NULLwhen a wrong-datapidis set. The thing is that in order to get the value forX-TIMESTAMP-MAP,data_nodeneeds to be used. I don't know if the problem has to do with the fact-datapidis used. From what I understand it's not the fact we don't have subtitles that prevents from having a correctX-TIMESTAMP-MAPso it should be possible.@cfsmp3 commented on GitHub (Feb 15, 2020):
OK so cheating with datapid is not an an option :-(
Check out our list of samples.
https://drive.google.com/drive/folders/0B_61ywKPmI0TUUk5LXJPeG1feFE?usp=sharing
Specifically the UK TV one has one that says "no subs"
@ozt860071 commented on GitHub (Jun 22, 2021):
Sorry not to see this in 0.89.
(from CHANGES.TXT)
This is not implemented, either.
@cfsmp3 commented on GitHub (Jun 22, 2021):
https://github.com/CCExtractor/ccextractor/pull/1176/files
@ozt860071 commented on GitHub (Aug 1, 2021):
As you mentioned,
This needs to be resolved. I think the code is ready.
@AbHash-RixE commented on GitHub (Aug 18, 2025):
@cfsmp3 Should the header be present even if the subtitle is present but empty, or when the subtitle is not present at all?
@cfsmp3 commented on GitHub (Aug 19, 2025):
I'd say always, otherwise we're not generating a valid file.
@AbHash-RixE commented on GitHub (Aug 28, 2025):
Hey ! @cfsmp3
I’ve worked on a small improvement related to this issue.
I added logic to ensure that when
--timestamp-mapand--out=webvttis used and no captions are found, a defaultX-TIMESTAMP-MAP=MPEGTS:0,LOCAL:00:00:00.000line is still added to the.vttoutput. This improves compatibility with HLS players that require it, even for empty subtitle files.This doesn't add a toggle/option to enable/disable the header as originally proposed, but ensures that the WebVTT output is valid in the no-caption case.
I plan to open a separate issue and PR for this, as it's a self-contained fix.
Let me know if this is useful or if you'd prefer I incorporate it under this issue/PR directly.
Thanks!
@AbHash-RixE commented on GitHub (Sep 8, 2025):
@cfsmp3 Hey! I’ve opened a PR regarding the issue—can you take a look when you get a chance?
issue-#1743
@sairajsachinpatil commented on GitHub (Jan 26, 2026):
From the later discussion and recent changes, it seems the project direction has settled on always including the X-TIMESTAMP-MAP header for WebVTT output to ensure HLS compliance, even for empty subtitle files.
The practical issue of missing headers in no-caption cases appears to be addressed by the fix in #1743 / PR #1772. Given that, the original proposal to make the header optional may no longer be necessary.
Feel free to close this issue if this matches the current intended behavior.