Caption Conversion Guide
Convert SAMI to WebVTT
The archive migration: a Windows Media era caption library moving to a modern web player. Two features of SAMI make this more than a reformat. It has no end times, and it holds every language in one file — so one input usually produces several outputs.
Can you convert a SAMI file to WebVTT?
Yes. Text, timing and basic styling all transfer. Two things need handling deliberately: end times have to be derived from the empty clearing entries SAMI uses to blank the screen, and each language class in the file becomes its own WebVTT track rather than staying in one file.
What changes when you convert SAMI to WebVTT
WebVTT is the natural destination for SAMI content, since both were designed for software players rather than broadcast. The structural differences are where the work is.
| Property | In the SAMI | In the WebVTT | Result |
|---|---|---|---|
| End times | None. An empty entry clears the screen | Explicit end on every cue | Derived from the clearing entries. Skip them and captions never clear |
| Languages per file | Several, one CSS class each | One per track | One SAMI becomes several WebVTT files |
| File encoding | Undeclared, often a Windows code page | UTF-8, mandatory | Identify the source encoding, then always write UTF-8 |
| Text | HTML-like markup | Plain text with inline tags | Transfers |
| Styling | CSS in the head, per class | CSS in STYLE blocks, ::cue selectors | Maps conceptually. Player support varies |
| Text colour | CSS colour per class | CSS via ::cue | Transfers, subject to what the player renders |
| Italics and bold | Inline tags or CSS | Inline tags | Transfers |
| Positioning | CSS, unreliable in practice | Cue settings | Rarely worth carrying across. Verify against the player |
| Timing precision | Milliseconds | Milliseconds | Transfers directly. No frame rate involved |
| Required header | <SAMI> root element | The word WEBVTT on the first line | Must be written or no browser will load the track |
Before you start: encoding, and how many files you will get
SAMI predates the convention of declaring an encoding, and it predates the idea that one caption file holds one language. Both assumptions have to be unwound.
- The source encoding. Most surviving SAMI files use a Windows code page rather than UTF-8. Opened with the wrong assumption, accented characters become symbol pairs.
- How many language classes the file defines. Read the CSS block in the head. Each class becomes a separate WebVTT file.
- Which language each class represents. The class definitions carry a name and a language attribute, which become your output filenames and track labels.
- Whether the clearing entries are present. A well-formed SAMI blanks the screen with empty entries. A file missing them will produce captions with no natural end.
- Whether the CSS positioning is worth keeping. SAMI positioning was unreliable even in its own era.
How to convert SAMI to WebVTT
The order matters: identify the encoding before reading the text, and identify the language classes before splitting the output.
-
Open the SAMI in a text editor
Confirm it is SAMI rather than SMIL — both use the.smiextension. A SAMI file has a root element and a CSS style block. -
Identify the source encoding
If accented characters appear as symbol pairs, the file is a Windows code page being read as UTF-8. Re-open with the correct encoding before doing anything else. -
Read the CSS block and list the language classes
Each class definition is a language. Note the class names and language codes; these determine how many output files you will produce. -
Derive end times from the clearing entries
Empty entries mark where a caption should disappear. Each one becomes the end time of the caption before it. -
Split the languages into separate tracks
Extract each class into its own set of cues. One WebVTT file per language, named with a language code. -
Map the CSS styling
Translate class colours into WebVTT CSS classes. Decide whether SAMI's positioning is worth carrying; usually it is not. -
Write each file with the WEBVTT header and UTF-8 encoding
The first line must readWEBVTTor no browser will load the track. Save as UTF-8. -
Test in the target player
Load each track and confirm the captions appear, clear correctly, and that the language selector shows every track.
What breaks, and how to catch it
Three of these produce a file that looks correct in a text editor and fails in a player.
- Ignored clearing entries. The commonest failure. Every caption stays on screen until the next line of dialogue, which on a programme with pauses looks obviously wrong.
- A missing WEBVTT header. The first line must read
WEBVTT. Without it browsers reject the track silently, showing no captions and no error. - Merged languages. Converting without splitting the CSS classes produces one file with every language interleaved at the same timecodes.
- Encoding damage. A Windows code page read as UTF-8 corrupts accented characters, and once the mis-decoded text is saved the original characters cannot be recovered.
- Carried-over positioning. SAMI's CSS positioning was inconsistent even in Windows Media Player. Carrying it into WebVTT can place captions worse than the default would.
When not to convert SAMI to WebVTT
WebVTT is almost always the right target for this material. The exceptions are about the destination rather than the source.
- The destination is broadcast. SCC or MCC is required, and the conversion needs a frame rate the SAMI does not have.
- The destination is a streaming platform with its own spec. IMSC is usually what those platforms name.
- Something downstream requires SRT. SRT is a valid target too, with the same end-time derivation and the same language split.
- The SAMI has no clearing entries. Derived durations will be unreliable and the file may need timing work rather than a conversion.
The SAMI format reference covers the format's structure and its multi-language design.
SAMI to WebVTT questions
Specific questions about this conversion. For the formats themselves, see the SAMI and WebVTT references below.
Because the clearing entries were ignored. SAMI has no end times: a caption stays on screen until a later synchronisation point replaces it, and files signal a gap by including an entry with empty text. A converter that skips those entries has no end time to derive, so every caption runs on until the next line of dialogue arrives.
One per language class defined in the CSS block. SAMI holds several languages in a single file, each caption tagged with the class it belongs to, while WebVTT is one language per track. A three-language SAMI becomes three WebVTT files, which the player then offers as three selectable subtitle tracks.
UTF-8, without exception — WebVTT requires it. The harder question is the input: most surviving SAMI files use a Windows code page and carry no declaration, so the correct source encoding has to be identified first. Read the original correctly, write UTF-8, and check accented characters in the output before considering the job done.
Not necessarily. SMIL, an unrelated multimedia layout format, also uses the .smi extension. Open it in a text editor: a SAMI file has a root element and a CSS style block defining caption classes, while a SMIL file is XML describing a presentation. If you can read caption text in it, it is SAMI.
Usually not. SAMI positioned captions through CSS, and support for it was inconsistent even in the players it was designed for, so the values in an archive file may never have rendered as intended. WebVTT's default bottom-centre placement is generally a better result than faithfully reproducing a position that never worked.
Migrate the library, not one file at a time
Closed Caption Creator reads SAMI with the correct encoding, derives end times from the clearing entries, and splits each language class into its own WebVTT track.
Batch a whole archive through the API and check the output in your player before the old system is retired.