Cueson documentation

Capability direction

The published 1.2.0 executable and current source provide optional consumer speaker attribution and declared media timing. Downstream applications assign IDs and determine their scope; Cueson stores those results separately from native speaker observations. Cue and declared-media checks catch out-of-range timed assignments. The release highlights and downloads describe these shipped additions. The v1.2.0 schema and documentation are prepared in S035; production activation remains tracked by issue #86. After the owner merges the reviewed S035 PR, the same slice continues immediately through authorized exact-main deployment and independent live verification.

• Preserve original source bytes, names, hashes, and observable filesystem metadata.
• Expose cue timing, raw text, plain text, line structure, speakers, and token timing through a stable common model.
• Retain format-native structures and surface unsupported or lossy interpretations through diagnostics.
• Keep the Cueson JSON Schema and official executable versioned together.
• Deliver portable native binaries for Windows, macOS, and Linux.

The ratified implementation baselines cover architecture, the Cue JSON schema, and the CLI contract. Dedicated format pages define the stable SubRip, WebVTT, and bounded ASS/SSA contracts. The broader Cueson Project Specification remains a working roadmap, and the media-format guide explains the longer-term format landscape and product intent.

The official Cueson identity is retained in the repository as the complete brand kit. See the Cueson brand guide for provenance, integrity verification, asset selection, licensing boundaries, and the official ShruggieTech download.

The v1.2.0 history, immutable schema and maintained release page are bound to immutable annotated tag v1.2.0 at 6a1fd7a541767c0b19dcc10022fafc0e46903cff. The v1.2.0 GitHub Release publishes the exact six archives, six SPDX JSON SBOMs and checksum manifest accepted by exact-main proof. Release verification records the independent public-byte check, and the governed release process keeps milestone closure, signatures, attestations, public schema hosting and production actions separately authorized.

The development roadmap records the v1.1.0 ASS/SSA milestone and later XML, SAMI, broadcast and bitmap/OCR work. Current source and the public v1.2.0 release provide the frozen bounded ASS/SSA profile, all twelve distinct conversion directions, complete CLI discovery, privacy-safe inspection, conformance hardening and exact source restoration. The v1.2.0 executable retains exact historical 1.0.0 and 1.1.0 input support; the published older executables reject unsupported new output, including output encoded from SubRip/WebVTT. Schema-only and complete experimental capability observations remain valid under the exact current identity without being rewritten.

S029 finalized the dated history, bound exact-main revision 7ff45c1d8cd8df377e1fb568b9785286b649fd7c and thirteen public assets to fresh accepted proof, and independently verified the authorized tag and release. S030 completed the v1.1.0 public schema/site outcome; S032 repaired and revalidated the protected deployment path. S033 merged through PR #83, completing consumer attribution issue #82. S034 prepared the exact 1.2.0 candidate, and issue #85 completed the authorized tag, release and thirteen-asset publication with independent verification. S035 completes the matching schema/site deployment after reviewed preparation and the final owner merge.

Installation

Download the archive for your platform from the v1.2.0 GitHub Release or the versioned download table, and verify it with cueson_1.2.0_checksums.txt. Six pure-Go archives cover Windows, macOS and Linux on amd64 and arm64, and each archive has a matching SPDX JSON SBOM.

Developers building from source require Go 1.25.0 or newer. Clone the repository, then use go run ./cmd/cueson, go build ./cmd/cueson, or go install ./cmd/cueson. The published release remains pure Go with CGO_ENABLED=0. Versioned public schemas resolve at https://cueson.io/schema/vVERSION/cueson.schema.json; the schema embedded in each executable and archive remains available without network access.

Executable quick start

Run these examples from the repository root. Create an empty quickstart directory first. Every input below is a committed, redistributable fixture, and every created file stays beneath that scratch directory. Existing destinations are refused unless --force is explicitly supplied.

go run ./cmd/cueson version

Expected result for current source and the published v1.2.0 executable: exit status 0, stdout is exactly 1.2.0 plus LF, and stderr is empty. Historical executables retain their own exact release versions.

go run ./cmd/cueson encode --pretty --output quickstart/document.cueson.json testdata/fixtures/conversion/srt-loss-free/source/input.srt

Expected result: exit status 0, stdout and stderr are empty, and quickstart/document.cueson.json is valid Cue JSON containing the exact source bytes in its source envelope.

go run ./cmd/cueson restore --no-metadata --output quickstart/restored.srt quickstart/document.cueson.json

Expected result: exit status 0 with empty stdout and stderr. quickstart/restored.srt is byte-for-byte identical to testdata/fixtures/conversion/srt-loss-free/source/input.srt; restore does not render the structured cue model.

go run ./cmd/cueson render --to srt --output quickstart/rendered.srt quickstart/document.cueson.json

Expected result: exit status 0 with empty stdout and stderr. quickstart/rendered.srt is canonical LF SubRip produced from the structured model and is not claimed to preserve the source's original bytes.

go run ./cmd/cueson convert --strict --no-speaker-detection --to vtt --output quickstart/converted.vtt testdata/fixtures/conversion/srt-loss-free/source/input.srt

go run ./cmd/cueson convert --strict --to srt --output quickstart/converted.srt testdata/fixtures/conversion/webvtt-loss-free/source/input.vtt

Both governed inputs are explicitly loss-free for the requested direction. Each command exits 0 with empty stdout and stderr and writes parser-valid native output. For other inputs, normal conversion reports every known loss on stderr; --strict rejects the complete conversion before publishing any output when one or more losses exist. See the conversion contract.

go run ./cmd/cueson validate testdata/fixtures/webvtt/minimal/source/minimal.vtt

Expected result: exit status 0, empty stdout, and one successful-validation diagnostic on stderr. --quiet suppresses that success diagnostic; --silent also suppresses warnings.

go run ./cmd/cueson inspect testdata/fixtures/webvtt/minimal/source/minimal.vtt

go run ./cmd/cueson inspect --json testdata/fixtures/webvtt/minimal/source/minimal.vtt

Each inspection command exits 0 with its report on stdout and no stderr for this fixture. Reports contain bounded structural facts, not preserved source bytes, content text, caller paths, usernames, hostnames, or other local identifiers.

go run ./cmd/cueson completion bash > quickstart/cueson.bash

Expected result: exit status 0 and one deterministic UTF-8 LF Bash completion definition on stdout, redirected here to the scratch file. Cueson does not modify a shell profile.

The complete command, option, alias, stream, exit-status, overwrite, and strict-mode behavior is in the CLI contract. The compatibility contract defines the stable v1 boundary, platform targets, immutable release surfaces, and production verification requirements.

Development

Development is specification-driven with GitHub Spec Kit. Run the product tests and build with go test ./... and go build ./cmd/cueson. Repository publication formatting, executable-documentation checks, and offline link verification run through scripts/github-format and scripts/docs-verify as described in CONTRIBUTING.md.

The default branch is protected by pull-request, resolved-conversation, squash-only, deletion, non-fast-forward and strict current-base rules. Required CI and CodeQL checks cover schema and conformance, native platforms, race detection, static analysis, vulnerability analysis and pure-Go cross-builds. The non-publishing release proof and the independently verified v1.2.0 publication record are documented in release verification.

Report security concerns privately through GitHub Security Advisories rather than a public issue.

License

Licensed under the Apache License 2.0. Copyright 2026 ShruggieTech.