SDK source API

Markdown · Agent index

A typed interface to the local Yapwing CLI. The CLI connects to the owning app when a project is open, and takes the same owner lock when it is closed. The SDK never evaluates a project file or rewrites JSON behind the app.

The SDK is private source and is not a public npm package. The build commands below require an authorized checkout of this directory; use the bundled CLI when you do not have source access.

Build with the pinned dependencies:

npm ci
npm run build
npm test

Run these commands in this directory. Node.js 22 or newer is recommended. The packaged CLI must be on PATH, or set YAPWING_CLI to its absolute path. A CLI built from source also needs the core library and speech paths described in docs/development.md.

import { ProjectClient } from "@yapwing/project";

const client = new ProjectClient("/absolute/my-video");
const { snapshot } = await client.inspect();
const first = snapshot.renderPlan.words.find(unit => unit.kind === "word");
if (!first) throw new Error("Wait for transcription, then inspect again.");

const request = client.request(snapshot, "edit-a-persisted-unique-id", [
  { type: "cut_units", unitIds: [first.id] },
]);
await client.check(request);
const { receipt } = await client.apply(request);
console.log(receipt.committedRevision);

Keep the complete request and its operation ID until success is known. After a transport interruption, retry exactly that request: the durable receipt prevents a duplicate edit even if its expected revision is now old. Reusing an ID with a different request fails. A new edit needs a new ID and a newly inspected revision.

A correction changes caption/transcript text while retaining its audio coverage:

const { snapshot } = await client.inspect();
const word = snapshot.renderPlan.words.find(unit => unit.kind === "word");
if (!word) throw new Error("No recognized speech.");
const correction = client.request(snapshot, "correct-persisted-id", [{
  type: "correct_words",
  occurrenceId: word.occurrenceId,
  atomIds: word.atomIds,
  text: "Corrected spelling",
}]);
await client.check(correction);
await client.apply(correction);

The core validates correction scope and length. Corrections cannot create recorded speech or new timing. Some recognizer tokens share one observed timing range; those tokens form one indivisible unit. Cutting a unit removes precisely its represented coverage. Listen to real footage to judge the recognized text and the sound of each cut; native/speech/README.md describes that check.

The project methods are init, import, collect, transcribe and export. The library methods follow below. All mutations take an inspected projectId and expectedRevision; import/collect also require a stable operationId. Import waits for transcription by default. Setting wait to false requires an open app to own the background job. Transcribe always waits. Export preserves existing output files; choose a new filename. With a CLI from the current private development source, its receipt’s loudness reports the measured level and the one gain that brought the mix to −14 LUFS.

search and preview need a CLI from the current private development source. search({query, limit?, shows?}) finds sentences said in library videos and returns {hits, revision}; shows: true adds picture matches once the person has downloaded the optional picture model, and shows.state says whether pictures were searched. preview({range?, frames?, audio?, projectId?, expectedRevision?}) renders stills (and an optional AAC snippet) of the current edit into a new temporary folder without changing the project. Both are read-only; see the agent guide.

Use import(paths, {...mutation, library: true}) to register sources without placing clips. projection: "equirectangular" explicitly marks a prepared 2:1 sphere. library({query, offset, limit}) reads verified cached metadata and corrected speech without starting analysis. analyze({...revision, assetId?, wait?}) retries derived analysis; linkPrepared(rawId, preparedId, revision) associates an imported raw recording with its prepared video. These methods return {items, total, nextOffset, revision}; follow nextOffset until null. Linking and analysis have no authored edit receipt. See the library guide.

Import replies also include importedAssetIDs in accepted command order. Library aliases coalesce; repeated timeline placements retain repeated IDs. The IDs stay the same on replay even when the returned snapshot includes later edits. Use these IDs to link a prepared video, since flat and spherical interpretations can share a path. Older CLIs omit this field; treat exact selection identity as unavailable instead of guessing it from paths or asset order.

Inspect returns { snapshot, statuses }. TranscriptionIncompleteError preserves that inspection after a successful import with failed speech work; the media remains in the project. YapwingError.code exposes structured validation errors. UncertainOperationError means the transport cannot establish whether an operation completed; it does not mean the operation was rolled back.

The executable cut example in examples/cut-unit.ts saves its request before applying it and can resume after interruption. The generated types in src/generated.ts mirror the project and command format; commands and render plans are validated by the Rust core.