@tongue-core/sdk 0.0.0-stage → 0.1.0-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Backpine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,344 @@
-# Temporary Holding Version
+# @tongue-core/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Everything you do with a Tongue film, as a library: import its assets, plan and check it, draw
+frames, render video, open it in the studio, and list what the machine can render with. The
+`tongue` CLI is a thin shell over this package, so anything the CLI does an application can do
+here, with the same results. Built with Effect v4 (orchestration only: the per-frame path is plain
+TypeScript); a Promise facade is included for applications that don't use Effect.
+
+```bash
+bun add @tongue-core/sdk@next effect@4.0.6      # Bun ≥ 1.3; ffmpeg and ffprobe on the PATH
+```
+
+`effect` is a peer dependency: your application and the SDK share one copy of it, so the SDK's
+services, errors and Layers are the same values as yours.
+
+## Promise API
+
+```ts
+import { createTongue } from "@tongue-core/sdk";
+
+const tongue = createTongue();
+await tongue.init("my-film", { template: "social-post" });            // a film project from a template
+const { build } = await tongue.build("my-film");                       // my-film/dist: film.json, build.json, bundles
+await tongue.stills("my-film", { frames: [0, 30], outDir: "out/hook", scene: { id: "hook" } });   // one scene alone
+const { text, summary } = await tongue.info("src/film.tsx");          // the timeline, as text and JSON
+const report = await tongue.check("src/film.tsx");                    // { ok, problems, warnings }: never rejects for a broken film
+await tongue.sheet("src/film.tsx", { frames: [0, 90, 300], outDir: "out/look" });
+const video = await tongue.render("src/film.tsx", { out: "out/film.mp4", from: 90, to: 300, scale: 0.5 });
+const machine = await tongue.backends();                               // rasters and encoders that work here
+```
+
+Failures reject with the SDK's tagged errors (below).
+
+## Effect API
+
+```ts
+import { openFilm, renderVideo, TongueServices } from "@tongue-core/sdk";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const film = yield* openFilm("src/film.tsx");          // load, import assets, plan
+  return yield* renderVideo(film, { out: "out/film.mp4", encoder: "auto", raster: "auto" });
+});
+await Effect.runPromise(program.pipe(Effect.provide(TongueServices.layer)));
+```
+
+`TongueServices.layer` is what every SDK function runs on (the file system, paths and child
+processes, from Bun): provide it once, where your application runs its Effects.
+
+| Function | Does |
+|---|---|
+| `initProject(dir, { template, name })` | a film project in a new or empty folder, from a built-in template or a template folder |
+| `listTemplates()` / `readTemplate(nameOrPath)` | the built-in templates, or one by name or path |
+| `buildFilm(project, { out, media })` | builds a film project into `out` (default `dist/`): build.json, film.json, a bundle per scene; `media` configures acquisition and hosted previews |
+| `openFilm(path, { scene, sources, media })` | a film ready to render: a project is built (into `.tongue/builds/<id>`, named by its content) and planned from film.json, a build folder (what `buildFilm` writes) is opened as it is, a film module is imported and planned; assets imported either way. `scene: { id, props }` opens one scene of a project on its own; `sources` overrides video originals; `media` configures hosted-media acquisition and caching ([Footage](#footage)) |
+| `describeFilm(film)` | the plan as text (for agents to read) and as a JSON summary |
+| `checkFilm(path)` | problems and warnings as data |
+| `renderStills(film, { frames, scale, outDir })` / `renderSheet(…)` | PNGs drawn by the wasm raster (the player's), or tiled into one labelled sheet |
+| `renderVideo(film, options)` | an MP4 with sound: the whole film or `[from, to)`, at any scale (`out` defaults to `out/<name>.mp4`); `sound` runs [sound processing](#sound-processing-extensions); `onStart` once the request is checked and the raster, encoder and workers are chosen (`budget` says why that many workers: one per physical core, fewer when memory is short), `onProgress` while it draws. A frame that throws fails the render with `Frame <n>: <message>`. The result's `profile` says where the time went: milliseconds per stage of drawing, decoder starts, pieces encoded, and the wall time of each phase |
+| `renderVideoEvents(film, options)` | the same render as a `Stream` of `RenderEvent`s: `Started`, `Frames`, `Sound` (each processor's progress), `Joining`, then `Done` with the result |
+| `parsePoint`, `parseFrame`, `parseRange`, `clipRange`, `spreadFrames`, `everyFrames` | points in a film as people write them (`90`, `3s`, `50%`, `end`, `site`, `site+30`), for a command line or form of your own; bad ones fail with `InvalidRequest` saying how to write them |
+| `videoInputs(film)`, `checkVideoInputs(film)` | where each video is decoded from, and a check that every one is there |
+| `listBackends()` | every raster and encoder, each tried for real |
+| `studioServer(path, { port, remote })` | the studio on a project (rebuilt and reloaded on every edit) or on a build served anywhere |
+
+## Films and projects
+
+A **film project** is a folder with a `tongue.json` ([docs/film-json.md](../../docs/film-json.md)):
+`film.tsx`, `scenes/`, `kit/`, `lib/`, `assets.ts`, `assets/`. It needs nothing installed: the SDK
+reads its files, compiles and bundles it with `@tongue-core/project`, loads the bundles with its own
+`@tongue-core/film`, imports the assets they declare (ffprobe gives media lengths), extracts film.json
+and writes the build. Everything renders from the build: in this process, in the render workers
+(they open build.json and the bundles), and in the studio (`tongue studio` serves the build; the
+browser fetches it). `.tongue/types/film` links to the SDK's `@tongue-core/film`, which the
+project's `tsconfig.json` points editors at.
+
+A **film module** (the way films were written before projects) is a `film.tsx` in a folder with a
+`package.json`. The SDK bundles it with Bun (into `.tongue/modules/`, JSX compiled for Tongue) against
+its own `@tongue-core/film`, the copy the engine reads, as it links a project's bundles, then plans
+it. The folder may install `@tongue-core/film` too, for its editor's types
+(`"jsx": "react-jsx", "jsxImportSource": "@tongue-core/film"` in its tsconfig); that copy isn't the one
+that runs.
+
+Local asset paths are relative to the root. Tongue writes `.tongue/` there for builds and render
+work, and renders to `out/`. Local converted assets use the project's cache; hosted-media
+downloads and preparation use the shared cache outside the project.
+
+A film's assets are what its modules declare (`font()`, `image()`, `audio()`, `video()`) while
+the SDK loads it, plus the media its clips play; `<Film assets={[…]}>` replaces the declared ones.
+Importing turns them into what the engine reads: TrueType fonts, QOI images, WAV audio, video facts
+and a poster frame.
+
+## Footage
+
+Hosted URLs are the normal source for application-owned media. Declare them with `video`, `audio`,
+`image` or `font`, with an explicit name and a SHA-256 when the application knows it. The SDK
+streams downloads into a shared cache outside the project, verifies content, and atomically
+promotes completed files. Concurrent requests for the same pinned content share a download.
+Unpinned URLs are revalidated with ETag/Last-Modified when available. Temporary network failures,
+408, 429 and server errors retry twice by default, with bounded backoff and Retry-After support;
+missing files, denied access and integrity failures are reported as `MediaFailure`.
+
+```ts
+const tongue = createTongue({
+  media: {
+    cacheDir: "/var/cache/tongue/media",
+    store: { directory: "/srv/media", baseUrl: "https://media.example/prepared/" },
+  },
+});
+await tongue.build("my-film");
+await tongue.render("my-film/dist", { out: "out/film.mp4" });
+```
+
+A portable build contains manifests and scene bundles, with media locations and hashes in
+`build.json` version 2. Originals and generated remote media are never copied into it. Local
+assets can still be packaged, and version 1 builds remain readable. The host must expose the
+configured store at its `baseUrl` (with CORS for browser clients). The CLI reads the equivalent
+`TONGUE_MEDIA_DIR`, `TONGUE_MEDIA_URL` and `TONGUE_MEDIA_CACHE` environment variables. The default
+cache is `$XDG_CACHE_HOME/tongue/media` or `~/.cache/tongue/media`. `tongue studio` supplies a
+local media store and serves it automatically.
+
+For object storage, provide `media.publish(upload)`, an Effect returning the uploaded file's
+HTTP(S) URL. `upload` holds the local `file`, `hash`, `bytes` and `contentType`. Storage belongs
+to the application. A publish callback must finish storing the bytes before returning its URL.
+Use the hash as an idempotent storage key and return a stable URL, so projects share uploaded
+bytes. The built-in directory store does this automatically. Invalid publisher locations fail
+before a portable build is written.
+
+Applications can prepare media at ingestion: `prepareMedia(asset, mediaOptions)` returns a
+`tongue.media` manifest with a canonical asset name, import recipe, source hash, duration and
+prepared files. Host that JSON and pass its URL as the declaration's `prepared` option. The same
+preparation is shared across projects and asset names. Preparation recipes include sizing and
+format versions, so incompatible results are rebuilt. Audio previews are sample-indexed WAV
+segments; video previews use the existing segmented H.264 format. Full-quality decoded audio
+remains available to final renders.
+
+`media.request(url, signal, headers)` can add authentication or refresh a signed URL without
+serializing credentials into the build. Preserve the supplied signal and conditional headers.
+`retries`, `retryDelayMs`, `timeoutMs`, `concurrency` and `onProgress` control acquisition. Original
+downloads default to a 30-minute timeout; metadata/preview requests default to two minutes.
+Cache contents are shared and host-managed; changing the cache directory isolates a job.
+
+Final rendering acquires and verifies its video originals before starting any frame worker.
+Converted assets are also acquired before use. Workers decode local files, with no networking
+in the per-frame path. A fully cached pinned build can render with networking disabled. Build
+snapshots retain immutable prepared-file bindings when a later version changes its assets.
+
+A render decodes every video from its **original file**: a build holds only a video's facts, a
+poster and a preview-quality proxy (what the studio plays). Before a frame is drawn, `renderVideo`
+and `renderStills` check that each video's file is there and fail with `AssetFailure` naming the
+ones that aren't; a frame ffmpeg can't decode, or a file shorter than its import counted, fails the
+render with `Frame <n>: Video "<name>": …` and ffmpeg's reason. A poster never stands in for
+footage in a render (that is the player's fallback while frames arrive).
+
+A local video is decoded from its source path under the film's root, unless `sources` says otherwise:
+
+```ts
+const film = yield* openFilm("renders/1234/dist", {   // a build, without the project around it
+  sources: { screen: "/data/media/screen.mp4", camera: "/data/media/camera.mp4" },
+});
+```
+
+A build inside a project (`my-film/dist`) finds local footage in the project; a build on its own
+needs `sources` for local videos that aren't beside it. Remote originals are resolved automatically
+from the pinned registry in the manifest.
+
+## Sound processing (extensions)
+
+A render can put part of its soundtrack through processing of your own (voice enhancement, noise
+removal, levelling, effects) and still produce one MP4, in sync. The SDK defines the contract and
+runs it; what a processor does and what it needs (a model, a native tool, a service) is yours, so
+nobody who doesn't use it installs it.
+
+```ts
+import { AudioProcessor, openFilm, renderVideo, Sound } from "@tongue-core/sdk";
+
+const enhance = yield* enhanceVoice({ peakDb: -3 });        // an AudioProcessor (below)
+yield* renderVideo(film, {
+  sound: [
+    Sound.track("voiceover", enhance),   // the clips of the track with id "voiceover"
+    Sound.track("voiceover", level),     // the same selection again: runs after enhance
+    Sound.master(loudness),              // then the whole mix
+  ],
+});
+```
+
+**What a rule takes.** `Sound.track(id, p)`; `Sound.stem({ clips: ["a", "b"] }, p)`;
+`Sound.stem({ voice: true }, p)` (every narration clip); `Sound.master(p)` (the whole mix, after
+the stems, before the limiter). A selection is data (`Sound.AudioSelection` decodes it from flags or
+JSON). The selected clips are mixed into a **stem** of their own (their trims, speed, gain and fades
+applied) across the whole film, processed, and added back; everything else sounds as it always has.
+A track or clip the film doesn't have, or a visual track, is an `InvalidRequest` listing what it
+does have; a clip goes into one stem, so overlapping selections are refused unless they are the same
+(then their processors run in order).
+
+**The contract.** A processor gets a `Stem`: `samples` per channel (the whole film at 48 kHz, from
+its first frame), `channels` (2), the stem as a float WAV `file` and as decoded `pcm`, the `clips` in
+it and the `plan`, a `workDir`, and `progress(0..1)`. It returns `{ pcm }` or `{ file }`, plus an
+optional `report` (any JSON). What it returns must have exactly the stem's rate, channels and
+length, and only finite samples, or the render fails with `ProcessorFailure`: that is what keeps
+the sound in sync, so a processor with a delay (a model's lookahead) takes it out itself. Any
+failure of the processor, or a defect in it, is a `ProcessorFailure` naming it.
+
+**Two ways to make one.** `AudioProcessor.fromPcm({ key, process: (pcm, stem) => pcm })` for
+processing that needs only the samples. `AudioProcessor.make({ key, process: (stem) => Effect })`
+for anything else: the services `process` uses are taken from where `make` runs and travel with the
+processor, so the render itself never needs them:
+
+```ts
+// voice-enhance: its own package, depending on @tongue-core/sdk and on what it needs.
+interface DenoiserOperations {
+  readonly name: string;
+  readonly denoise: (channel: Float32Array, sampleRate: number) => Effect.Effect<Float32Array>;
+}
+export class Denoiser extends Context.Service<Denoiser, DenoiserOperations>()("voice-enhance/Denoiser") {
+  static readonly layer = Layer.effect(Denoiser, loadModel);   // the heavy part, paid once, only by those who provide it
+}
+
+export const enhanceVoice = (settings: EnhanceSettings) =>
+  AudioProcessor.make({
+    key: `voice-enhance/v1 peak ${settings.peakDb} dB`,
+    process: (stem) => Effect.gen(function* () {
+      const denoiser = yield* Denoiser;
+      const pcm = yield* stem.pcm;
+      const channels = yield* Effect.forEach(pcm.channels, (c) => denoiser.denoise(c, pcm.sampleRate));
+      yield* stem.progress(1);
+      return { pcm: { sampleRate: pcm.sampleRate, channels }, report: { denoiser: denoiser.name } };
+    }),
+  });   // Effect<AudioProcessor, never, Denoiser>
+
+// In your command line: make the processor where its Layer is provided.
+const render = Command.make("render", { project: Argument.String("project"), enhance: Flag.String("enhance").pipe(Flag.atLeast(0)) },
+  Effect.fn(function* (flags) {
+    const film = yield* openFilm(flags.project);
+    const enhance = yield* enhanceVoice({ peakDb: -3 });
+    return yield* renderVideo(film, { sound: flags.enhance.map((track) => Sound.track(track, enhance)) });
+  }),
+).pipe(Command.provide(Denoiser.layer));
+```
+
+**The key and the cache.** A processor's `key` names it, its version and its settings. A result is
+cached by the key and the exact audio it was given (`.tongue/cache/sound`, the newest 32 kept): render
+again after changing anything that doesn't change that audio (the picture, another track, the
+range, the scale) and the processor doesn't run; the result says `cached: true`. Change the key
+whenever the output would change.
+
+**What happened.** `VideoResult.sound` lists each processor run: the stem, its clips, the
+processor's key, whether it was cached, its seconds and its report. `renderVideoEvents` streams
+`Sound` events (`started`, `progress`, `done`, `cached`) while it runs.
+
+**Where it runs.** Processors run in your process, alongside the render workers, while the frames
+are drawn (the soundtrack always has); keep heavy work off its main thread (`effect/workers`, a
+child process), or it slows the hand-off of frames to the workers.
+
+## How a video renders
+
+```
+coordinator ──segments──▶ worker 1: frames ─▶ raster ─▶ encoder ─▶ piece-000000.mp4
+            ◀─progress──  worker 2 …                              piece-000280.mp4
+            soundtrack:   sounds + audio clips ─▶ mix ─▶ AAC        audio.m4a
+              with sound processing: stems ─▶ processors (here, cached) ─▶ sum ─▶ master ─▶ limiter ─▶ AAC
+            join:         concat + audio ─(stream copy)─▶ film.mp4, frame count probed
+```
+
+- **Workers** are processes (`src/render/worker.ts`), one per physical core by default, fewer when
+  the memory available wouldn't hold that many (`src/render/budget.ts`). Each loads
+  the film and its raster once and draws every segment it is sent, so the JIT stays warm and glyphs
+  and images stay uploaded.
+- **Segments** are a quarter to half a second of frames: what a worker is given at a time. Each
+  worker starts on its own contiguous run of them; one that finishes early takes over the later
+  half of the longest run left (`src/render/runs.ts`). So every worker draws long contiguous
+  stretches, and its video decoders read straight through instead of seeking.
+- **Pieces** are what is encoded: each contiguous stretch a worker draws goes to one encoder, as one
+  closed-GOP file; the join copies streams without re-encoding. Which pieces a render makes depends
+  on how the work was shared out; the frames don't.
+- **Video clips** are decoded by ffmpeg from their original files, in order, frame after frame, a
+  few frames ahead, through a FIFO that holds ffmpeg back when it gets ahead; restarted on jumps,
+  a window at a time for clips playing backwards, and closed when unused. A frame that can't be
+  decoded fails the render ([Footage](#footage)).
+- **The soundtrack** is mixed in its own process while the workers draw (`soundtrack-process.ts`);
+  with sound processing, it writes the stems, the processors run in the coordinator, and it adds
+  them back, limits and encodes (`sound/soundtrack.ts`).
+
+Rasters (who draws) and encoders (who encodes) are chosen by name, because the choice is made here
+but runs inside the workers:
+
+| Raster | |
+|---|---|
+| `native` | the Rust raster built for x86-64-v3 (`@tongue-core/raster-linux-x64`); byte-identical to wasm, 2–3× faster |
+| `wasm` | the engine's embedded WebAssembly raster, the browser player's; runs anywhere |
+| `gpu` | EGL + GLES 3.1; within a few levels of the CPU rasters, never chosen by `auto` |
+
+Encoders: `x264` (veryfast, crf 14), `vaapi-hevc` / `vaapi-h264` (constant QP 18 / 16, with
+CPU-conversion variants), and `nvenc-*` / `qsv-*` (written from vendor documentation, untested).
+`auto` takes the first that works of nvenc-hevc, vaapi-hevc, vaapi-hevc-cpuconv, qsv-hevc, x264.
+
+On this machine (16 threads, AMD GPU) the 35.5 s demo renders at 1080p with sound in about 12 s
+(≈ 87 fps) with `native` + `vaapi-hevc`.
+
+## Errors
+
+Every failure is a `Schema.TaggedError` with a message that says what to change. `exitCodeOf`
+gives the CLI's exit code.
+
+| Error | When | Exit |
+|---|---|---|
+| `FilmFailure` | the module is missing, throws, isn't a `<Film>`, or its timeline doesn't plan | 2 |
+| `AssetFailure` | an asset's file is missing or unreadable, or a video's original file isn't there to render from | 2 |
+| `InvalidRequest` | a frame outside the film, a bad range or scale | 2 |
+| `ToolFailure` | ffmpeg or ffprobe is missing or failed | 3 |
+| `BackendUnavailable` | the raster or encoder asked for doesn't work here | 3 |
+| `RenderFailure` | a worker died, a frame failed, or a video frame couldn't be decoded | 3 |
+| `ProcessorFailure` | a sound processor failed, or returned audio that would break sync (rate, channels, length) or isn't audio | 3 |
+| `LayoutError`, `CompileError`, `LoadError`, `TimelineError`, `DocError`, `TemplateError` | a film project doesn't build (from `@tongue-core/project`: each names its file, line or path) | 2 |
+
+## Environment
+
+| Variable | |
+|---|---|
+| `TONGUE_FFMPEG`, `TONGUE_FFPROBE` | the tools' paths (default: `ffmpeg`, `ffprobe` on the PATH) |
+| `TONGUE_NATIVE_RASTER`, `TONGUE_GPU_RASTER` | a raster library to use instead of `@tongue-core/raster-linux-x64`'s |
+| `TONGUE_VAAPI_DEVICE` | the render node for VAAPI and Quick Sync (default `/dev/dri/renderD128`) |
+
+## Layout
+
+```
+src/
+  index.ts, client.ts     the Effect API and the Promise facade
+  project.ts              projects, openFilm and buildFilm
+  build/build.ts          building a film project on this machine: its files, a module host, the build folder, editor types
+  init.ts                 init from templates
+  check.ts, backends.ts   checkFilm, listBackends
+  import/                 asset import: fonts, images, audio, video (ffprobe, posters)
+  render/                 stills, the video pipeline and its events, its worker and soundtrack processes, video decoding and inputs
+  sound/                  sound processing: Sound (rules), AudioProcessor (the contract), the soundtrack around them
+  points.ts               points and ranges in a film, as people write them
+  TongueServices.ts       the layer the SDK runs on
+  encode/encoders.ts      the ffmpeg encoders and how each is tried
+  raster/                 the native and GPU raster bindings (index.ts) and the registry (rasters.ts)
+  studio/server.ts        the studio's server: the app bundled, a project's build served and rebuilt
+test/                     unit tests, end-to-end ones on fixtures/tiny (a film with text, video and sound; sound
+                          processing and footage that can't be decoded on copies of it), builds rendered with `sources`, and
+                          projects from every template (project.test.ts: film.json draws the same frames as film.tsx)
+```

package/dist/TongueServices.d.ts

@@ -0,0 +1,5 @@
+import { BunServices } from "@effect/platform-bun";
+import type { Layer } from "effect";
+/** The services every SDK function needs. */
+export type TongueServices = BunServices.BunServices;
+export declare const layer: Layer.Layer<TongueServices>;

package/dist/TongueServices.js

@@ -0,0 +1,2 @@
+import { BunServices } from "@effect/platform-bun";
+export const layer = BunServices.layer;

package/dist/backends.d.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import { type EncoderName } from "./encode/encoders.js";
+import { type RasterName } from "./raster/rasters.js";
+export interface BackendsReport {
+    readonly rasters: ReadonlyArray<{
+        readonly name: RasterName;
+        readonly available: boolean;
+        readonly exact: boolean;
+        readonly summary: string;
+    }>;
+    readonly encoders: ReadonlyArray<{
+        readonly name: EncoderName;
+        readonly available: boolean;
+        readonly hardware: boolean;
+        readonly tested: boolean;
+        readonly summary: string;
+    }>;
+    /** What `auto` picks here. */
+    readonly auto: {
+        readonly raster: RasterName;
+        readonly encoder: EncoderName | null;
+    };
+}
+export declare const listBackends: () => Effect.Effect<BackendsReport, import("effect/Config").ConfigError, never>;

package/dist/backends.js

@@ -0,0 +1,17 @@
+import { Effect } from "effect";
+import { AUTO_ENCODERS, DEFAULT_SETTINGS, ENCODER_NAMES, ENCODER_SUMMARIES, encoderSpec, encoderWorks } from "./encode/encoders.js";
+import { autoRaster, RASTERS } from "./raster/rasters.js";
+import { ffmpegPath } from "./tools.js";
+export const listBackends = Effect.fn("listBackends")(function* () {
+    const ffmpeg = yield* ffmpegPath;
+    const encoders = yield* Effect.forEach(ENCODER_NAMES, (name) => Effect.promise(async () => {
+        const spec = encoderSpec(name, DEFAULT_SETTINGS, 30);
+        return { name, available: await encoderWorks(ffmpeg, spec), hardware: spec.hardware, tested: spec.tested, summary: ENCODER_SUMMARIES[name] };
+    }), { concurrency: "unbounded" });
+    const report = {
+        rasters: RASTERS.map((r) => ({ name: r.name, available: r.available(), exact: r.exact, summary: r.summary })),
+        encoders,
+        auto: { raster: autoRaster().name, encoder: AUTO_ENCODERS.find((n) => encoders.some((e) => e.name === n && e.available)) ?? null },
+    };
+    return report;
+});

package/dist/build/build.d.ts

@@ -0,0 +1,51 @@
+import type { Asset, MediaInfo, SceneDefinition } from "@tongue-core/film";
+import { type Build, type ModuleHost, type ProjectFiles } from "@tongue-core/project";
+import { Effect, FileSystem, type PlatformError } from "effect";
+import { type ImportReport } from "../import/importer.js";
+import type { Project } from "../project.js";
+import { type MediaOptions } from "../media/cache.js";
+/** A project's code and data: every .ts, .tsx and .json file outside hidden folders and the ones
+ *  tools write. */
+export declare const readProjectFiles: (root: string) => Effect.Effect<ProjectFiles, PlatformError.PlatformError, FileSystem.FileSystem>;
+/** Loads bundles by writing each to `dir` (named by its hash, so written once) and importing it. */
+export declare const fileModuleHost: (dir: string) => ModuleHost;
+/** Points the project's `.tongue/types/film` at this SDK's @tongue-core/film (tsconfig.json reads it). */
+export declare const linkFilmTypes: (root: string) => Effect.Effect<void, PlatformError.PlatformError, FileSystem.FileSystem>;
+export interface BuiltProject {
+    readonly assetsDir: string;
+    readonly build: Build;
+    /** Where the build was written. */
+    readonly dir: string;
+    readonly imported: ImportReport;
+    /** The scenes the bundles export, by id: what film.json is assembled with. */
+    readonly scenes: ReadonlyMap<string, SceneDefinition>;
+    readonly media: MediaInfo;
+}
+/** The imported files a film's assets are (a video is its facts, its poster and its proxy's
+ *  segments), with their sizes and hashes: what build.json lists. */
+export declare const importedFiles: (project: Project, assets: readonly Asset[]) => Effect.Effect<{
+    readonly path: string;
+    readonly bytes: number;
+    readonly hash: string;
+    readonly url?: string | undefined;
+}[], PlatformError.PlatformError, FileSystem.FileSystem>;
+/** How a written build reaches its assets: copies of the files (a build to publish), or a link to
+ *  the project's imported assets (a build for Tongue's own use). */
+export type AssetPlacement = {
+    readonly kind: "copy";
+    readonly from: string;
+} | {
+    readonly kind: "link";
+    readonly to: string;
+};
+/** Writes a build to `dir`, replacing the build that was there (old bundles and assets included). */
+export declare const writeBuildFiles: (dir: string, build: Build, assets: AssetPlacement) => Effect.Effect<void, PlatformError.PlatformError, FileSystem.FileSystem>;
+/** Keeps a build in `.tongue/builds/<id>`, named by its content and never rewritten, so renders
+ *  reading one build are never disturbed by the next. Written to a temporary folder first and moved
+ *  into place, so a build folder is either whole or not there. */
+export declare const keepBuild: (project: Project, build: Build) => Effect.Effect<string, PlatformError.PlatformError, FileSystem.FileSystem>;
+/** Builds a film project into `dir` (what `tongue build` does: dist/ by default), replacing what
+ *  was there, with copies of its imported assets: a folder any static host can serve. */
+export declare const buildFilmProject: (project: Project, dir: string, options?: MediaOptions | undefined) => Effect.Effect<BuiltProject, import("../errors.js").AssetFailure | import("../errors.js").ToolFailure | import("@tongue-core/project/media").MediaFailure | import("@tongue-core/project").LayoutError | import("@tongue-core/project").CompileError | import("@tongue-core/project").LoadError | import("@tongue-core/project").TimelineError | import("@tongue-core/project").DocError | import("effect/Config").ConfigError | PlatformError.PlatformError | import("effect/Schema").SchemaError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | import("effect/Path").Path>;
+/** Builds a film project for Tongue's own use (stills, renders, dev): kept in .tongue/builds. */
+export declare const buildForWork: (project: Project, options?: MediaOptions | undefined) => Effect.Effect<BuiltProject, import("../errors.js").AssetFailure | import("../errors.js").ToolFailure | import("@tongue-core/project/media").MediaFailure | import("@tongue-core/project").LayoutError | import("@tongue-core/project").CompileError | import("@tongue-core/project").LoadError | import("@tongue-core/project").TimelineError | import("@tongue-core/project").DocError | import("effect/Config").ConfigError | PlatformError.PlatformError | import("effect/Schema").SchemaError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | import("effect/Path").Path>;