@miadi/capture

The capture core abstracted from gmtermux — a take lifecycle state machine over a pluggable capture driver, one TLID naming rule, and provenance that survives the process that captured it.

A capture is any take a device makes in one unrepeatable instant — kinds: audio | video | midi | other. Captures include video ("I wanna be able to shoot video"); the lifecycle, the TLID rule, and the sidecar are the same for every kind, because none of them ever learned what a microphone is.

Extraction contract: gmtermux/rispecs/composition-recorder-suite.spec.md (the recording aspect) and gmtermux/rispecs/recording.spec.md. Vocabulary: @miadi/episodic-memory-schema (CaptureProvenance, ArtifactOrigin, ArtifactReference) — consumed, never re-declared.

What this package owns

• Recorder — start / pause / resume / stop with lossless segment join. Context freezes at start() (the Songbird rule); every failure leaves more than nothing (graded degradation): a join that cannot happen retains its segments and the recorder stays paused.
• TLID — YYMMDDHHMMSS, the take's local-instant name. Previously implemented three times in gmtermux; this is the one copy.
• TakeStore — the flat take library plus a <take>.take.json provenance sidecar, closing the defect where provenance lived only in process memory and degraded to file mtime after a restart.
• CaptureDriver / SegmentJoiner — the device seam. Termux, ALSA, or any host that owns a capture device implements these; the lifecycle never learns which.

What this package refuses to own

• Association. A take is durable before it belongs to anything. Binding a take to a musical-composition is the studio domain's act (@miadi/musical-composition); binding to a chronicle episode belongs to @miadi/inquiry-weave / @miadi/musical-composition-to-episode. This package only guarantees there is something whole to associate, and toArtifactReference() to speak the episode vocabulary when asked.
• Transport. The HTTP envelope lives in @miadi/capture-client.
• Bytes at rest beyond the library directory. Registries (medicine-wheel's capture records) hold records and URIs, never media.

The origin law

A take is captured: a device, an instant, one chance — irreplaceable. Its transcription is derived — regenerable for exactly as long as the voice is kept. TakeStore.readTakeRecord refuses a sidecar whose origin fails the guard rather than defaulting it, because defaulting to derived marks an unrepeatable take safe to delete.

Example

import { Recorder, TakeStore } from "@miadi/capture"

const store = new TakeStore(process.env.CAPTURES_DIR ?? "./captures")
const recorder = new Recorder({
  driver: platformDriver,   // your CaptureDriver
  joiner: ffmpegJoiner,     // your lossless SegmentJoiner
  recordingsDir: store.dir,
  device: "larix",
})

await recorder.start({ composition: "ep097-ceremony" }) // context freezes here
await recorder.pause()
await recorder.resume()
const take = await recorder.stop()      // provenance: startedAt, duration, bytes, device
await store.recordCompletedTake(take)   // provenance now survives a restart