CCEXTRACTOR(1)
π CCEXTRACTOR(1) π
okay bestie, quick heads up: this is section 1, the User Commands manual, and it's all about CCExtractor β the closed captions extractor. Buckle up, there's a LOT. π
πΈ NAME πΈ
CCExtractor β closed captions extractor. that's it, that's the whole vibe. π
π SYNOPSIS π
ccextractor [options] inputfile1 [inputfile2...] [-o outputfilename]
[-o1 outputfilename1] [-o2 outputfilename2]
β¨ DESCRIPTION β¨
It pulls closed captions and teletext subtitles out of video streams, periodt. The formats known to actually work: DVB, .TS, ReplayTV 4000 and 5000, dvr-ms, bttv, Tivo, Dish Network, .mp4, and HDHomeRun. π¦
It can do two things:
- Save the data to a "raw", unprocessed file that you can later feed into other tools. πΎ
- Generate a subtitles file (
.srt,.smi, or.txt) that you can use directly with your favourite player. π¬
π OPTIONS π
π File name related options π
inputfileβ the file(s) to process. π-o outputfilenameβ use-oto name your output file if the default names aren't it (defaults are the same as infile plus_1or_2when needed, plus the file extension, e.g..srt).-cf filenameβ write 'clean' data to a file. "Clean" means the ES without TS or PES headers. no clutter, just the good stuff. β¨-stdoutβ write output to stdout (console) instead of a file. If stdout is being used, then-o,-o1and-o2can't be used. Also,-stdoutredirects all messages to stderr (error). π-pesheaderβ dump the PES Header to stdout (console). This is for debugging purposes so you can peek at the contents of each PES packet header. π-debugdvbsubβ write the DVB subtitle debug traces to the console.-ignoreptsjumpsβ ignore PTS jumps (this is the default).-fixptsjumpsβ fix pts jumps. use this one if you're experiencing timeline resets/jumps in the output. π-stdinβ reads input from stdin (console) instead of a file.
You can pass as many input files as you need, and they'll be processed in order. If a file name is suffixed by +, ccextractor will try to follow a numerical sequence. For example, DVD001.VOB+ means DVD001.VOB, DVD002.VOB and so on until there are no more files. Output will be one single file (either raw or srt). Use this if you made your recording in several cuts (to skip commercials for example) but you want one subtitle file with contiguous timing. π₯
βοΈ Output file segmentation βοΈ
-outinterval xβ output in interval ofxseconds.--segmentonkeyonly,-keyβ when segmenting files, do it only after an I frame, trying to behave like FFmpeg. π«
π Network support π
-udp portβ read the input via UDP (listening in the specified port) instead of reading a file.-udp [host:]portβ read the input via UDP (listening in the specified port) instead of reading a file. Host can be a hostname or IPv4 address. If host isn't specified, then it listens on the local host.-udp [src@host:]portβ read the input via UDP (listening in the specified port) instead of reading a file. Host and src can be a hostname or IPv4 address. If host isn't specified, then it listens on the local host.-sendto host[:port]β sends data in BIN format to the server according to the CCExtractor's protocol over TCP. For IPv6 use[address]:port. π‘-tcp portβ reads the input data in BIN format according to CCExtractor's protocol, listening on the specified port on the local host.-tcppassword passwordβ sets the server password for new connections to the tcp server. π-tcpdesc descriptionβ sends the server a short description about captions, e.g. channel name or file name.
π§ Options that affect what will be processed π§
-1,-2,-12β output Field 1 data, Field 2 data, or both (DEFAULT is-1).--appendβ prevents overwriting of existing files. The output will be appended instead. π«Ά-cc2β when in srt/sami mode, process captions in channel 2 instead of channel 1.-svc,--service N1[cs1],N2[cs2]...β enable CEA-708 (DTVCC) captions processing for the listed services. The parameter is a comma delimited list of service numbers, such as"1,2"to process the primary and secondary language services. Pass"all"to process all services found.
If captions in a service are stored in 16-bit encoding, you can specify what charset or encoding was used. Pass its name after the service number (e.g. "1[EUC-KR],3" or "all[EUC-KR]") and it will encode the specified charset to UTF-8 using iconv. See iconv documentation to check if the required encoding/charset is supported.
In general, if you want English subtitles you don't need to use these options, as they are broadcast in field 1, channel 1. If you want the second language (usually Spanish) you may need to try -2, or -cc2, or both. πͺπΈ
π₯ Input formats π₯
With the exception of McPoodle's raw format (which is just the closed caption data with no other info), CCExtractor can usually detect the input format correctly. To force a specific format:
-in=format
where format is one of these:
ts-> For Transport Streams.ps-> For Program Streams.es-> For Elementary Streams.asf-> ASF container (such as DVR-MS).wtv-> Windows Television (WTV)bin-> CCExtractor's own binary format.raw-> For McPoodle's raw files.mp4-> MP4/MOV/M4V and similar.mkv-> Matroska container and WebM.
-ts, -ps, -es, -mp4, -wtv and -asf (or --dvr-ms) can be used as shorts. π
π€ Output formats π€
-out=format
where format is one of these:
srt-> SubRip (default, so not actually needed). βass/ssa-> SubStation Alpha.webvtt-> WebVTT formatwebvtt-full-> WebVTT format with stylingsami-> MS Synchronized Accesible Media Interface.bin-> CC data in CCExtractor's own binary format.raw-> CC data in McPoodle's Broadcast format.dvdraw-> CC data in McPoodle's DVD format.txt-> Transcript (no time codes, no roll-up captions, just the plain transcription.ttxt-> Timed Transcript (transcription with time info)smptett-> SMPTE Timed Text (W3C TTML) format.spupng-> Set of.xmland.pngfiles for use with dvdauthor's spumux. See "Notes on spupng output format"null-> Don't produce any file outputreport-> Prints to stdout information about captions in specified input. Don't produce any file output
βοΈ Options that affect how input files will be processed βοΈ
-gt,--goptimeβ use GOP for timing instead of PTS. This only applies to Program or Transport Streams with MPEG2 data and overrides the default PTS timing. GOP timing is always used for Elementary Streams.-nogt,--nogoptimeβ never use GOP timing (use PTS), even if ccextractor detects GOP timing is the reasonable choice.-fp,--fixpaddingβ fix padding. some cards (or providers, or whatever) seem to send0000as CC padding instead of8080. If you get bad timing, this might solve it. π-90090β use90090(instead of90000) as MPEG clock frequency. (reported to be needed at least by Panasonic DMR-ES15 DVD Recorder)-ve,--videoeditedβ by default, ccextractor will process input files in sequence as if they were all one large file (i.e. split by a generic, non video-aware tool). If you are processing video that was split with an editing tool, use-veso ccextractor doesn't try to rebuild the original timing.-s,--stream [secs]β consider the file as a continuous stream that is growing as ccextractor processes it, so don't try to figure out its size and don't terminate processing when reaching the current end (i.e. wait for more data to arrive). If the optional parameter secs is present, it means the number of seconds without any new data after which ccextractor should exit. Use this parameter if you want to process a live stream but not kill ccextractor externally.
Note: If -s is used then only one input file is allowed.
-poc,--usepicorderβ use thepic_order_cnt_lsbin AVC/H.264 data streams to order the CC information. The default way is to use the PTS information. Use this switch only when needed.-mythβ force MythTV code branch.-nomythβ disable MythTV code branch. The MythTV branch is needed for analog captures where the closed caption data is stored in the VBI, such as those with bttv cards (Hauppage 250 for example). This is detected automatically so you don't need to worry about this unless autodetection doesn't work for you.-wtvconvertfixβ this switch works around a bug in Windows 7's built in software to convert*.wtvto*.dvr-ms. For analog NTSC recordings the CC information is marked as digital captions. Use this switch only when needed.-wtvmpeg2β read the captions from the MPEG2 video stream rather than the captions stream in WTV files.-pn,--program-numberβ in TS mode, specifically select a program to process. Not needed if the TS only has one. If this parameter is not specified and CCExtractor detects more than one program in the input, it will list the programs found and terminate without doing anything, unless-autoprogram(see below) is used. π-autoprogramβ if there's more than one program in the stream, just use the first one we find that contains a suitable stream.-datapidβ don't try to find out the stream for caption/teletext data, just use this one instead.-datastreamtypeβ instead of selecting the stream by its PID, select it by its type (pick the stream that has this type in the PMT).-streamtypeβ assume the data is of this type, don't autodetect. This parameter may be needed if-datapidor-datastreamtypeis used and CCExtractor cannot determine how to process the stream. The value will usually be2(MPEG video) or6(MPEG private data).-haup,--hauppaugeβ if the video was recorded using a Hauppauge card, it might need special processing. This parameter will force the special treatment. π₯-mp4vidtrackβ in MP4 files the closed caption data can be embedded in the video track or in a dedicated CC track. If a dedicated track is detected it will be processed instead of the video track. If you need to force the video track to be processed instead, use this option.-noautotimeref
Okay so some streams roll up with broadcast date info already baked in. When that data is available, CCExtractor sets its time reference to whatever it received. Use this parameter if you'd rather keep your own reference instead. π«Ά Heads up though: currently this only affects Teletext in timed transcript with -datets.
--noscte20β SCTE-20 data? If it's there, ignore it. Simple as that. π--webvtt-create-cssβ Make a whole separate file for the CSS instead of inlining it.-deblevβ Turns on debug so the calculated distance for every pair of strings gets printed. The output shows both strings, the calculated distance, the maximum allowed distance, and whether the strings are ultimately considered equivalent or not β meaning the calculated distance is less than or equal to the max allowed. Full transparency, bestie. π-anvid,--analyzevideoβ Analyze the video stream even when it's not being used for subtitles. This lets you get video information out of it. π
π Levenshtein distance π
When it's processing teletext files, CCExtractor tries to fix typos by comparing consecutive lines. If line N+1 is almost identical to line N except for tiny changes (plus next characters), it assumes line N had a typo that got corrected in N+1. This is currently only implemented for teletext, because that's where the sample files that could actually benefit from it were available. You can tune β or fully disable β the algorithm with these parameters. β¨
-nolevdistβ Don't even try to correct typos with Levenshtein distance.-levdistmincnt valueβ The minimum distance we always allow, no matter how long the strings are. Default2. So if the calculated distance is0,1or2, we consider the strings equivalent. π-levdistmaxpct valueβ The maximum distance we allow, expressed as a percentage of the shortest string's length. Default10%. For example, picture comparing one string of 30 characters against one of 60 characters. We want to know whether the first 30 characters of the longer string are more or less the same as the shortest string β i.e. whether the longest string is just the shortest one plus new characters and maybe some corrections. Since the shortest string is 30 characters and the default percentage is 10%, we'd allow a distance of up to 3 between the first 30 characters.
β¨ Options that affect what kind of output will be produced β¨
-chapters(Experimental) β Produces a chapter file from MP4 files. Note that this must only be used with MP4 files β for other files it will simply generate a subtitles file. No cap.-bomβ Append a BOM (Byte Order Mark) to output files. Note that most text processing tools in linux will not be into BOM. π This is the default in Windows builds.-nobomβ Do not append a BOM (Byte Order Mark) to output files. Note that this may break files when using Windows. This is the default in non-Windows builds.-unicodeβ Encode subtitles in Unicode instead of Latin-1.-utf8β Encode subtitles in UTF-8 (no longer needed, because UTF-8 is now the default).-latin1β Encode subtitles in Latin-1.-nofc,--nofontcolorβ For.srt/.sami/.vtt, don't add font color tags.--nohtmlescapeβ For.srt/.sami/.vtt, don't escape html unsafe characters.-nots,--notypesettingβ For.srt/.sami/.vtt, don't add typesetting tags.-trimβ Trim lines.-dc,--defaultcolorβ Pick a different default color (instead of white). This causes all output in.srt/.smi/.vttfiles to have a font tag, which makes the files larger. Add the color you want in RGB, like-dc #FF0000for red. π-sc,--sentencecapβ Sentence capitalization. Use this if you hate ALL CAPS in subtitles.-sbs,--splitbysentenceβ Split output text so each frame contains a complete sentence. Timings get adjusted based on number of characters.--capfile,-caf fileβ Add the contents offileto the list of words that must be capitalized. For example, iffileis a plain text file containing:
Tony
Alan
Whenever those words are found they'll be written exactly as they appear in the file. Use one line per word. Lines starting with # are considered comments and discarded. π
-unixts REFβ For timed transcripts that have an absolute date instead of a timestamp relative to the file start, use this time reference (UNIX timestamp).0=> use current system time. ccextractor will automatically switch to transport stream UTC timestamps when available.-datetsβ In transcripts, write time asYYYYMMDDHHMMss,ms.-sectsβ In transcripts, write time asss,ms.-UCLAβ Transcripts are generated with a specific format that's convenient for a specific project. Feel free to play with it, but be aware that this format is really live β don't rely on its output format not changing between versions. β οΈ-lfβ Use LF (UNIX) instead of CRLF (DOS, Windows) as line terminator.-autodashβ Based on position on screen, attempt to determine the different speakers and a dash (-) when each of them talks (.srt/.vttonly,-trimrequired).-xmltv modeβ Produce an XMLTV file containing the EPG data from the source TS file. Mode:1= full output,2= live output,3= both.-semβ Create a.semfile for each output file that is open and delete it on file close.-dvbcolorβ For DVB subtitles, also output the color of the subtitles, if the output format is SRT or WebVTT.-nodvbcolorβ In DVB subtitles, disable color in output.-dvblangβ For DVB subtitles, select which language's caption stream will be processed. e.g.'eng'for English. If there are multiple languages, only this specified language stream will be processed (default).-ocrlangβ Manually select the name of the Tesseract.traineddatafile. Helpful if you want to OCR a caption stream of one language using the data of another language. e.g.'-dvblang chs -ocrlang chi_tra'will decode the Chinese (Simplified) caption stream but perform OCR using the Chinese (Traditional) trained data. This option is also helpful when the traineddata file has non-standard names that don't follow ISO specs. π§-oemβ Select the OEM mode for Tesseract. Could be0,1or2.0:OEM_TESSERACT_ONLYβ default value, the fastest mode.1:OEM_LSTM_ONLYβ use LSTM algorithm for recognition.2:OEM_TESSERACT_LSTM_COMBINEDβ both algorithms.-mkvlangβ For MKV subtitles, select which language's caption stream will be processed. e.g.'eng'for English. Language codes can be either the 3 letters bibliographic ISO-639-2 form (like"fre"for french) or a language code followed by a dash and a country code for specialities in languages (like"fre-ca"for Canadian French).-nospupngocrβ When processing DVB, don't use the OCR to write the text as comments in the XML file.-fontβ Specify the full path of the font that's to be used when generating SPUPNG files.
π Options that affect how ccextractor reads and writes (buffering) π
-bi,--bufferinputβ Forces input buffering.-nobi,-nobufferinputβ Disables input buffering.-bs,--buffersize valβ Specify a size for reading, in bytes (suffix withKorMfor kilobytes and megabytes). Default is16M.-kocβ keep-output-close. If used, CCExtractor will close the output file after writing each subtitle frame and attempt to create it again when needed.-ff,--forceflushβ Flush the file buffer whenever content is written.
π Options that affect the built-in 608 closed caption decoder π
-druβ Direct Roll-Up. When in roll-up mode, write character by character instead of line by line. Note that this produces (much) larger files. π-noru,--norollupβ If you hate the repeated lines caused by the roll-up emulation, you can have ccextractor write only one line at a time, getting rid of those repeated lines.-ru1/-ru2/-ru3β Roll-up captions can consist of 2, 3 or 4 visible lines at any time (the number of lines is part of the transmission). If having 3 or 4 lines annoys you, you can use-ruto force the decoder to always use 1, 2 or 3 lines. Note that 1 line is not a real rollup mode, so CCExtractor does what it can. In-ru1the start timestamp is actually the timestamp of the first character received, which is possibly more accurate. β¨
β° Options that affect timing β°
-delay msβ For srt/sami/webvtt, add this number of milliseconds to all times. For example,-delay 400makes subtitles appear 400ms late. You can also use negative numbers to make subs appear early. β±οΈ
Notes on times: -startat and -endat times are used first, then -delay. So if you use -srt -startat 3:00 -endat 5:00 -delay 120000, ccextractor will generate a .srt file, with only data from 3:00 to 5:00 in the input file(s), and then add that (huge) delay, which would make the final file start at 5:00 and end at 7:00. π
π― Options that affect what segment of the input file(s) to process π―
-startat timeβ Only write caption information that starts after the given time. Time can be seconds,MM:SSorHH:MM:SS. For example,-startat 3:00means 'start writing from minute 3'.-endat timeβ Stop processing after the given time (same format as-startat). The-startatand-endatoptions are honored in all output formats. In all formats with timing information, the times are unchanged.-scr,--screenfuls numβ Writenumscreenfuls and terminate processing.
π§ Options that affect which codec is to be used have to be searched in input π§
If codec type is not selected, then the first elementary stream suitable for subtitle is selected. Please consider -teletext / -noteletext override this option.
-codec dvbsubβ Select the dvb subtitle from all elementary streams. If a stream of dvb subtitle type is not found, then nothing is selected and no subtitle is generated.-nocodec dvbsubβ Ignore dvb subtitle and follow default behaviour.-codec teletext-codec teletextβ picks the teletext subtitle out of the elementary stream-nocodec teletextβ just ignores the teletext subtitle entirely
NOTE, and bestie this one actually matters: options written like-foo=bar,-foo = baror--foo=barare invalid. The only valid form is-foo bar, periodt. Alsonocodecandcodecmust not be the same β if they are, thenocodecparameter gets ignored. Pass this flag once; more than one isn't supported yet and the last parameter is the one that gets taken into consideration. π«Ά
π¬ Adding start and end credits π¬
CCExtractor can try to add a custom message (credits, for example) at the start and at the end of the file, by hunting for a window where there are no captions. If there's no such window, then no text gets added at all, sorry. The start window has to fall between the times you give it, and it has to have enough time to display the message for at least the duration you specified. β¨
--startcreditstext txtβ write this text as the start credits. If it's several lines, separate them with the characters\n, likeLine1\nLine 2.--startcreditsnotbefore timeβ don't show the start credits before this time (inS, orMM:SS). Default:0--startcreditsnotafter timeβ don't show the start credits after this time (inS, orMM:SS). Default:5:00--startcreditsforatleast timeβ start credits need to be displayed for at least this long (inS, orMM:SS). Default:2--startcreditsforatmost timeβ start credits should be displayed for at most this long (inS, orMM:SS). Default:5--endcreditstext txtβ write this text as the end credits. If it's several lines, separate them with the characters\n, likeLine1\nLine 2.--endcreditsforatleast timeβ end credits need to be displayed for at least this long (inS, orMM:SS). Default:2--endcreditsforatmost timeβ end credits should be displayed for at most this long (inS, orMM:SS). Default:5
π Options that affect debug data π
-debugβ show lots of debugging output. Like, a lot.-608β print debug traces from the EIA-608 decoder. If you're filing a bug report, please send the output from this option, k?-708β print debug information from the (currently in development π) EIA-708 (DTV) decoder.-gopptsβ enable lots of time stamp output.-xdsdebugβ enable XDS debug data (lots of it).-videsβ print debug info about the analysed elementary video stream.-cbrawβ print debug trace with the raw 608/708 data, with time stamps.-nosyncβ disable the syncing code. Only useful for debugging purposes.-fullbinβ disable the removal of trailing padding blocks when exporting to bin format. Only useful for debugging purposes.-parsedebugβ print debug info about the parsed container file. (Only for TS/ASF files at the moment.)-parsePATβ print a Program Association Table dump.-parsePMTβ print a Program Map Table dump.-dumpdefβ hex-dump defective TS packets.-investigate_packetsβ if no CC packets are detected based on the PMT, try to find data in all packets by scanning.
πΊ Teletext related options πΊ
-tpage pageβ use this page for subtitles (if this parameter isn't used, it tries to autodetect). In Spain the page is always888, though it may vary in other countries.-tverboseβ enable verbose mode in the teletext decoder.-teletextβ force teletext mode even if teletext isn't detected. If you use this, you should also pass-datapidto specify the stream ID you want to process.-noteletextβ disable teletext processing. This might be needed for video streams that have both teletext packets and CEA-608/708 packets (if teletext is processed then CEA-608/708 processing is disabled).
π Transcript customizing options π
-customtxt formatβ use the passed format to customize the (Timed) Transcript output. The format must look like this:1100100(7 digits). These tell it whether the next things should be displayed or not in the (timed) transcript. In order, they represent:- Display start time
- Display end time
- Display caption mode
- Display caption channel
- Use a relative timestamp (relative to the sample)
- Display XDS info
- Use colors
Examples, bestie, take notes:
0000101 is the default setting for transcripts
1110101 is the default for timed transcripts
1111001 is the default setting for -ucla
Make sure you use this parameter after the others that might affect these settings (-out, -ucla, -xds, -txt, -ttxt ...). Order matters, fr fr.
π¬ Communication with other programs and console output π¬
--gui_mode_reportsβ report progress and interesting events tostderrin an easy to parse format. This is intended to be used by other programs. See thedocsdirectory for details.--no_progress_barβ suppress the output of the progress bar.-quietβ don't write any message. Shhh. π€«
Notes on the CEA-708 decoder: while it's starting to be useful, it's a work in progress. A number of things don't work yet in the decoder itself, and many of the auxiliary tools (case conversion, to name one) won't do anything yet. Feel free to submit samples that cause problems, plus feature requests. π
Notes on spupng output format: one .xml file is created per output field. A set of .png files is created in a directory with the same base name as the corresponding .xml file(s), but with a .d extension. Each .png file will contain an image representing one caption and is named subNNNN.png, starting with sub0000.png.
For example, this command:
ccextractor -out=spupng input.mpg
will create the files:
input.xml
input.d/sub0000.png
input.d/sub0001.png
...
And this command:
ccextractor -out=spupng -o /tmp/output -12 input.mpg
will create the files:
/tmp/output_1.xml
/tmp/output_1.d/sub0000.png
/tmp/output_1.d/sub0001.png
...
/tmp/output_2.xml
/tmp/output_2.d/sub0000.png
/tmp/output_2.d/sub0001.png
...
π₯ Burned-in subtitle extraction π₯
-hardsubxβ enable the burned-in subtitle extraction subsystem.
NOTE: the following options will work only if -hardsubx is specified before them. Order is not a vibe, it's a requirement. π
-ocr_modeβ set the OCR mode to either frame-wise, word-wise or letter wise. e.g.-ocr_mode frame(default),-ocr_mode word,-ocr_mode letter-subcolorβ specify the color of the subtitles. Possible values are in the set{white,yellow,green,cyan,blue,magenta,red}. Alternatively, a custom hue value between1and360may also be specified. e.g.-subcolor whiteor-subcolor 270(for violet). Refer to an HSV color chart for values.-min_sub_durationβ specify the minimum duration that a subtitle line must exist on the screen. The value is specified in seconds. A lower value gives better results, but takes more processing time. The recommended value is0.5(default). e.g.-min_sub_duration 1.0(for a duration of 1 second)-detect_italicsβ specify whether italics are to be detected from the OCR text. Italic detection automatically enforces the OCR mode to be word-wise.-conf_threshβ specify the classifier confidence threshold between1and100. Try and use a threshold which works for you if you get a lot of garbage text. e.g.-conf_thresh 50-whiteness_threshβ for white subtitles only, specify the luminance threshold between1and100. This threshold is content dependent, and adjusting values may give you better results. Recommended values are in the range80to100. The default value is95
An example command for burned-in subtitle extraction goes like this:
ccextractor video.mp4 -hardsubx -subcolor white -detect_italics
-whiteness_thresh 90 -conf_thresh 60
--versionβ display the current CCExtractor version and detailed information. Slay.
π SEE ALSO π
This tool's homepage:
http://www.ccextractor.org
Originally based on McPoodle's tools. Check his page for lots of information on closed captions technical details.
http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_TOOLS.HTML
okay that's the whole page, bestie!! π this was CCExtractor 0.86, dated April 2018, credited to Carlos Fernanβ¦ (yeah the name literally gets cut off in the source, iconic π), and it's the CCEXTRACTOR(1) manual. go forth and extract those captions, you absolute legend. πβ¨
π¦ where this page comes from
- ubuntu jammy: ccextractor 0.93+ds2-2 Β· GPL-2.0-only
- ubuntu noble: ccextractor 0.94+ds1-3build3 Β· GPL-2.0-only
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms