Subtitles

Reads and parses a subtitle file. Returns false when it cannot be read or is malformed; the problem is reported through the log. Free the result with free.

Parses subtitle text, which opens with a [1] version line. :name starts a section (::name marks it finalized), =speaker 1.5 starts a timed instant, the lines after it are speech, ++ text is a stage direction, and +name parameter begin end adds an event. The sections point into data, which must outlive them. short_name names the source in error messages.

text := "[1]\n:intro\n=guard 1.5\nHalt!\n++ raises a hand\n";
ok, subtitles := load_subtitles_from_memory(text, "intro");
assert(ok);
section := subtitles.all_sections[0];
assert(section.name == "intro" && section.instants[0].speaker == "guard");
assert(section.instants[0].lines.count == 2);
free(*subtitles);

Frees the sections and tables, and the text itself when load_subtitles_from_file read it.

The sections in which any of the named characters speak.

Writes subtitles back out in the text form load_subtitles_from_memory reads, starting with a [1] version line. The caller frees the string.

Appends a complete HTML page showing sections as dialogue, one block per section. Lines of character_to_emphasize are highlighted; name_map swaps speaker ids for display names.

Appends one section as an HTML block, without the page around it. See format_sections_as_html.

Returns s in double quotes with inner quotes doubled, as a CSV field. The caller frees it.

Appends a recording script as CSV: a header row, then one row per speaker turn with its dialogue, directions and the wav file names to record into.

Appends one section's CSV rows. See format_sections_as_csv.

Writes the CSV row for one speaker's gathered lines, if any of them has text.

Dialogue scripts for games: sections of timed speech, stage directions and events. Load text with load_subtitles_from_memory or load_subtitles_from_file, write it with serialize, and turn sections into a reading page (format_sections_as_html) or a recording sheet (format_sections_as_csv).

A named scene or conversation: its instants and events in order.

One line of a section: something a character says, or a stage direction.

A moment of dialogue: one speaker, the lines they say, and when (-1 when untimed). A speaker of _ in the source reads back as an empty speaker.

A named cue (an animation or sound, say) with an optional parameter, tied to an instant or to explicit start and end times. A time of -1 is unset.

The format version serialize writes in its [1] header line.