libcaption

libcaption is a C library designed for creating and parsing closed caption data. It implements a subset of EIA608 and CEA708 standards, specifically targeting the implementation used by the Apple iOS platform to ensure cross-platform consistency.

Key features include:

• EIA608 Support: Encoding and decoding of control and preamble codes, with support for Basic North American (BNA), Special North American (SNA), and various Extended Western European (WES, WEF, WEP, WEG) character sets.
• CEA708 Support: Encoding 608 data into the NTSC field 1 user data type structure.
• H.264 Utilities: Functions to wrap 708 payloads into h.264 SEI (Supplementary Enhancement Information) NALUs. This involves prepending specific header bytes (nal_unit_type = 6, payloadType = 4) and appending a stop bit (value 127), including emulation prevention for start codes.

The flv+srt tool supports live captioning by reading an SRT file from a named pipe.

Behavioral Notes:

• The input must be formatted as valid SRT.
• If a null character is received on the pipe, the internal SRT buffer is cleared.
• After a null character, the first SRT timestamp encountered is treated as 'immediate', and those captions will begin on the next video frame.

To caption a file that is not in FLV format (like an MP4), you must use ffmpeg to remux the file to an FLV stream, pipe it into flv+srt, and then pipe the result back into ffmpeg to remux it to your desired output format.

ffmpeg -i in.mp4 -codec copy -f flv - | flv+srt - in.srt - | ffmpeg -i - -codec copy out.mp4

To build libcaption on macOS or Linux, you must first install the necessary build dependencies: git, cmake, a compiler (such as xcode, gcc, or clang), and optionally re2c and ffmpeg.

Follow these steps to compile and install:

# Standard build with re2c if available
cmake . && make

# Build without re2c
cmake -DENABLE_RE2C=OFF . && make

# Install the library
sudo make install

To add captions from an SRT file to an existing FLV file, use the flv+srt tool. You can provide direct file paths or use standard streams.

# Using file paths
`flv+srt in.flv in.srt out.flv`

# Using stdin/stdout
`flv+srt in.flv in.srt - >out.flv`

libcaption supports several character sets used in captioning:

• BNA: Basic North American
• SNA: Special North American
• WES: Extended Western European (Extended Spanish/Miscellaneous)
• WEF: Extended Western European (Extended French)
• WEP: Extended Western European (Portuguese)
• WEG: Extended Western European (German/Danish)

The following tools are available in the examples directory. All tools accept FLV as either a file path or via stdin/stdout using - as the argument.

- `flv2srt` - reads a 608/708 captioned flv file and writes an srt file.
- `flv+srt` - encodes an srt file to 608/708 into pop-on captions and combines it with an existing flv, resulting in a new file
- `flv+scc` - same as flv+srt, but accepts an scc as input. However pin on/rool up is available as it is already encoded in the scc.
- `scc2srt` - converts an scc file to a srt file
- `ts2srt` - same as flv2srt, but reads from a mpeg2 transport stream
- `add_captions` - A shell script that utilizes ffmpeg to remux files to/from flv to simplify captioning non flv file. (Note: This is an example script and is not installed by `make install`).