Cassini

cassini is the product CLI for recording Nextcloud Talk meetings into one portable meeting file that can later be loaded in the web app.

The normal user flow is:

1. point Cassini at a meeting
2. let Cassini record and process it
3. end up with one portable .opus file

Cassini still uses .run, .meeting, and .site artifacts internally, but those are now implementation detail and debugging surfaces rather than the main product story.

Repo Entry Point

From this source checkout, use:

./bin/cassini

That wrapper builds the current cassini CLI from the Go module and runs it from your current working directory.

First Commands

See what the product exposes:

./bin/cassini --help

Validate the environment before expensive work starts:

./bin/cassini doctor

If doctor reports an unwritable Cassini cache or model directory, fix that path or point Cassini at a writable cache root before building:

export CASSINI_CACHE_ROOT="$PWD/.cache/cassini"
./bin/cassini doctor

Main Flow

Set your Talk room URL:

export CALL_URL="https://cloud.example.com/call/<ROOM_TOKEN>"

Record a meeting and let Cassini finish with one portable file:

./bin/cassini record --call "$CALL_URL" --out "./My Meetings/2026-03-11 Weekly Sync.opus"

If Cassini fails after capture or during processing, fix the issue and rerun the same command with the same --out path. Cassini now keeps resumable state in a hidden .cassini-work/ directory next to the target file and will reuse the finished recording or finished meeting artifact when possible.

Inspect the resulting file:

./bin/cassini inspect "./My Meetings/2026-03-11 Weekly Sync.opus"

If you already have an existing recording, build the portable file from that:

./bin/cassini build /path/to/meeting.mkv --out "./My Meetings/Imported Meeting.opus"

Try It Without A Real Call

The user-facing portable-file path currently needs a real meeting.

For local smoke and diagnostics, simulate mode still writes a debug .run bundle:

./bin/cassini record --simulate --out ./runs/demo.run
./bin/cassini inspect ./runs/demo.run

Browse an already-generated sample site from this checkout:

./bin/cassini serve ./cassini-viewer/exports/static-meetings

If you have processed .opus recordings, build a browser view of them in one step:

cd cassini-viewer
npm install
npm run build
node ./scripts/export-static-meetings.mjs \
  --source-dir /path/to/your/processed-opus \
  --output-dir /tmp/cassini-opus-view
cd ..
./bin/cassini serve /tmp/cassini-opus-view

Advanced Flow

If you want to keep the internal working artifacts visible, you can still use the explicit pipeline:

./bin/cassini record --call "$CALL_URL" --out ./runs/weekly-sync.run
./bin/cassini build ./runs/weekly-sync.run --out ./meetings/weekly-sync.meeting
./bin/cassini publish ./meetings --out ./site
./bin/cassini serve ./site

Inspect any primary Cassini artifact:

./bin/cassini inspect "./My Meetings/2026-03-11 Weekly Sync.opus"
./bin/cassini inspect ./runs/weekly-sync.run
./bin/cassini inspect ./meetings/weekly-sync.meeting
./bin/cassini inspect ./site

Installing On Nextcloud

The production install path is the Nextcloud AppAPI ExApp — registration, Talk recording handoff, verification checklist, and GPU setup are covered in:

• docs/exapp-install.md

Project Governance

• License: GNU AGPLv3
• Changelog: CHANGELOG.md
• Security reporting: SECURITY.md
• Contribution notes: CONTRIBUTING.md

Deployment Bundle

For the repo-root Docker Compose deployment bundle (development and staging — not the Nextcloud app install), see:

• deployment/README.md

From there you can bring up the packaged operator, control panel, and viewer with docker compose up --build.

Harness Commands

The local stack and showcase/demo flows now live under cassini dev:

./bin/cassini dev stack up
./bin/cassini dev room create --name "Local room"
cp .envrc.example .envrc
direnv allow
./bin/cassini dev smoke
./bin/cassini dev fixture prepare-showcase
./bin/cassini dev player showcase --call-url "$CALL_URL"

For local viewer development, pull demo data directly into the viewer dev server root. Set DEMO_DATA_URL in a gitignored .envrc or export it in your shell, then run:

cd cassini-viewer
npm install
npm run build
npm run demo-data:pull
npm run dev

Use npm run demo-data:clean to remove the pulled bundle.

The demo-data pull downloads index.html, referenced assets/*, catalog.json, and each meeting directory into cassini-viewer/exports/viewer-demo, which is where the Vite dev server already serves /catalog.json and /meetings/* from. Meeting file names are read from each meeting's manifest.json, so DEMO_DATA_URL remains the only required setting.

Current Constraints

• cassini build now uses the native Go transcription pipeline in cassini-go-recorder/internal/transcribe.
• cassini publish currently uses the static exporter under cassini-publisher/bin/export-static-meetings.sh.
• cassini doctor should be run before record --out ...opus or build --out ...opus; it catches cache, media-tool, and runtime issues early.
• In this checkout, the current doctor output is expected to fail if the Cassini cache or model directories are not writable, or if required media tools like ffmpeg/ffprobe are unavailable.

Product Commands

./bin/cassini doctor
./bin/cassini record
./bin/cassini build
./bin/cassini publish
./bin/cassini serve
./bin/cassini inspect
./bin/cassini meetings

cassini meetings reads published recordings back out of Nextcloud as a given Nextcloud user — see Agent access to meeting recordings.

Legacy Surface

Older wrappers under directories such as:

• cassini-recorder/
• cassini-diagnostics/
• cassini-publisher/
• cassini-lab/
• cassini-player/

are now legacy shims or implementation surfaces. They are being deprecated in favor of ./bin/cassini.

The local harness implementation now lives under harness/, and it is now being surfaced through ./bin/cassini dev ... rather than taught as a peer product.

Docs

• Start here: docs/README.md — curated index (concepts, install & configure, reference)
• System overview: docs/architecture.md
• Cross-cutting reference: docs/portable-meeting-format.md, docs/audio-glossary.md
• Component deep-dives: cassini-go-recorder/docs/ (active transcription lives here), cassini-viewer/docs/