VOX open transcript container

What it is

A .vox file is a ZIP archive that bundles audio, a canonical word-level transcript, and derived views so any tool can use the recording without Vox installed. The Vox desktop app reads the full JSON payload for editing; other apps can open the subtitles, Word document, or offline HTML player inside the package.

Design goals

• Self-contained interchange — one file travels with its audio and transcript.
• Graceful degradation — players, Word, and browsers each have a ready-made view.
• Full fidelity in Vox — channel labels, review state, notes, and metadata round-trip.
• Discoverability — every package ships a README and embedded spec at the archive root.

Container layout (v2)

Legacy v1 packages contain only manifest.json, transcript.json, and audio/*. Importers accept both generations.

Package vs sidecar

The .vox extension covers two shapes: a ZIP container (magic bytes PK) and a deprecated plain-JSON sidecar. Importers must sniff magic bytes — never assume .vox is always JSON.

For in-place workflows where audio stays on disk, use a co-located .vox.json sidecar beside the audio file. It uses the same canonical schema as transcript.json but does not embed media. Prefer the ZIP container when sharing or archiving.

Using a package without Vox

Unzip the archive once, then open the primary audio (e.g. audio/mix.flac) in VLC, QuickTime, or another media player. A matching audio/mix.vtt sits beside it so subtitles load automatically — no Vox install required.

Or open views/player.html in a browser, or run scripts under launch/. Read README.md at the package root for quick-start instructions.

manifest.json

Index file at the archive root. Identifies the package kind, format version, primary audio entry, derived view paths, bundled assets, and recommended applications when Vox is not installed.

{
  "kind": "vox-package",
  "formatVersion": "2.2.0",
  "version": 2,
  "primaryAudioEntry": "audio/recording_4ch.flac",
  "views": {
    "subtitlesVtt": "views/transcript.vtt",
    "subtitlesSrt": "views/transcript.srt",
    "document": "views/transcript.docx",
    "player": "views/player.html"
  },
  "recommendedApplications": [
    { "id": "vox-desktop", "name": "VOX-II / Vox", "role": "editor" },
    { "id": "browser-player", "name": "Web browser", "opens": "views/player.html" }
  ]
}

transcript.json

Canonical payload and source of truth inside the package. Required fields include version, audioPath, and a words array. Each word has start, end, and word; optional fields include speaker, confidence, review flags, and recorder channel.

Optional transcript-level fields cover paragraphs, case metadata, channel configuration, session notes, waveform peaks, and review workflow state. Derived views (VTT, SRT, DOCX, HTML player) are generated from this file.

Full specification

This page is a summary. The normative spec — including view generation rules, versioning policy, JSON Schema, test fixtures, and a minimal Python read example — lives in the project repository:

docs/VOX-FORMAT.md on GitHub

Cloud sync via Voxit uses a separate batch JSON API shape; it is not identical to on-disk .vox packages.