@tongue-core/sdk 0.1.0-rc.7 → 0.1.0-rc.9

package/README.md

@@ -51,12 +51,12 @@ processes, from Bun): provide it once, where your application runs its Effects.
 |---|---|
 | `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 })` | builds a film project into `out` (default `dist/`): build.json, film.json, a bundle per scene |
-| `openFilm(path, { scene, sources })` | 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 (cached by size, mtime and options) either way. `scene: { id, props }` opens one scene of a project on its own; `sources` says where videos are decoded from ([Footage](#footage)) |
+| `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 and encoder are chosen, `onProgress` while it draws. A frame that throws fails the render with `Frame <n>: <message>` |
+| `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 |
@@ -81,8 +81,9 @@ 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.
 
-Either way, asset paths are relative to the root, Tongue writes `.tongue/` there (imported assets,
-builds, render work) and renders to `out/`.
+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.
@@ -91,6 +92,59 @@ 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
@@ -98,7 +152,7 @@ ones that aren't; a frame ffmpeg can't decode, or a file shorter than its import
 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 video is decoded from its source path under the film's root, unless `sources` says otherwise:
+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
@@ -106,8 +160,9 @@ const film = yield* openFilm("renders/1234/dist", {   // a build, without the pr
 });
 ```
 
-A build inside a project (`my-film/dist`) finds its footage in the project; a build on its own
-needs `sources` for every video that isn't beside it.
+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)
 
@@ -200,20 +255,28 @@ child process), or it slows the hand-off of frames to the workers.
 ## How a video renders
 
 ```
-coordinator ──segments──▶ worker 1: frames ─▶ raster ─▶ encoder ─▶ seg-0000.mp4
-            ◀─progress──  worker 2 …                              seg-0001.mp4
+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. Each loads
-  the film and its raster once and renders every segment it is sent into that segment's own
-  encoder, so the JIT stays warm and glyphs and images stay uploaded.
-- **Segments** are one to two seconds of frames, shrinking towards the end so the last ones finish
-  together. Each is a closed-GOP encode; the join copies streams without re-encoding.
-- **Video clips** are decoded by ffmpeg from their original files, in order, frame after frame,
-  and restarted on jumps; a frame that can't be decoded fails the render ([Footage](#footage)).
+- **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`).

package/dist/build/build.d.ts

@@ -3,6 +3,7 @@ import { type Build, type ModuleHost, type ProjectFiles } from "@tongue-core/pro
 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>;
@@ -11,6 +12,7 @@ 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;
@@ -25,6 +27,7 @@ export declare const importedFiles: (project: Project, assets: readonly Asset[])
     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). */
@@ -43,6 +46,6 @@ export declare const writeBuildFiles: (dir: string, build: Build, assets: AssetP
 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) => Effect.Effect<BuiltProject, import("../errors.js").AssetFailure | import("../errors.js").ToolFailure | 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/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | import("effect/Path").Path>;
+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) => Effect.Effect<BuiltProject, import("../errors.js").AssetFailure | import("../errors.js").ToolFailure | 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/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | import("effect/Path").Path>;
+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>;

package/dist/build/build.js

@@ -14,6 +14,9 @@ import { compileProject, extractFilm, IGNORED_DIRS, loadProject, sha256, TYPES_L
 import { Effect, FileSystem } from "effect";
 import { importAssets } from "../import/importer.js";
 import { sdkVersion } from "../version.js";
+import { isRemoteSource } from "@tongue-core/project/media";
+import { mediaCacheDir, mediaLock } from "../media/cache.js";
+import { snapshotAssets } from "../media/snapshot.js";
 // Building a film project on this machine: read its code, compile and bundle it, run the bundles,
 // import the assets they declare (media lengths go into film.json), extract film.json and write
 // the build, with the imported asset files listed in build.json (and copied beside it, or linked,
@@ -99,6 +102,8 @@ export const writeBuildFiles = Effect.fn("writeBuildFiles")(function* (dir, buil
         return;
     }
     for (const file of build.manifest.assets.files) {
+        if (file.url !== undefined)
+            continue;
         const path = join(assetsDir, file.path);
         yield* fs.makeDirectory(dirname(path), { recursive: true });
         yield* fs.copyFile(join(assets.from, file.path), path);
@@ -135,28 +140,36 @@ const pruneBuilds = Effect.fn("pruneBuilds")(function* (builds, keep) {
 });
 /** A film project built in memory: compiled, its bundles run, its assets imported (their lengths
  *  go into film.json), film.json extracted. */
-const buildInMemory = Effect.fn("buildInMemory")(function* (project) {
-    const files = yield* readProjectFiles(project.root);
-    const compiled = yield* compileProject(files);
-    const loaded = yield* loadProject(compiled, fileModuleHost(join(project.workDir, "modules")));
-    const imported = yield* importAssets(project, loaded.assets);
-    const media = { duration: (asset) => imported.durations.get(`${asset.kind}:${asset.name}`) ?? null };
-    const doc = yield* extractFilm(loaded, { media });
-    const build = writeBuild(compiled, doc, { tongue: yield* sdkVersion, assets: yield* importedFiles(project, loaded.assets) });
-    yield* linkFilmTypes(project.root);
-    return { build, imported, scenes: new Map(loaded.scenes.map((s) => [s.id, s.scene])), media };
+const buildInMemory = Effect.fn("buildInMemory")(function* (input, options = {}) {
+    return yield* mediaLock(`project-build:${input.root}`, Effect.gen(function* () {
+        let project = input;
+        const files = yield* readProjectFiles(project.root);
+        const compiled = yield* compileProject(files);
+        const loaded = yield* loadProject(compiled, fileModuleHost(join(project.workDir, "modules")));
+        if (loaded.assets.some((asset) => isRemoteSource(asset.source)))
+            project = { ...project, assetsDir: join(mediaCacheDir(options), "projects", createHash("sha256").update(project.root).digest("hex"), "assets") };
+        const imported = yield* importAssets(project, loaded.assets, options);
+        const media = { duration: (asset) => imported.durations.get(`${asset.kind}:${asset.name}`) ?? null };
+        const doc = yield* extractFilm(loaded, { media });
+        const local = yield* importedFiles(project, loaded.assets.filter((asset) => !isRemoteSource(asset.source)));
+        const build = writeBuild(compiled, doc, { tongue: yield* sdkVersion, assets: [...local, ...(imported.remoteFiles ?? [])], originals: imported.originals });
+        if ((imported.originals?.length ?? 0) > 0 && !options.portable)
+            project = { ...project, assetsDir: yield* snapshotAssets(project.assetsDir, build.manifest.assets.files, imported.remoteFiles ?? [], options) };
+        yield* linkFilmTypes(project.root);
+        return { build, imported, scenes: new Map(loaded.scenes.map((s) => [s.id, s.scene])), media, assetsDir: project.assetsDir };
+    }));
 });
 /** 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 const buildFilmProject = Effect.fn("buildFilmProject")(function* (project, dir) {
-    const built = yield* buildInMemory(project);
-    yield* writeBuildFiles(dir, built.build, { kind: "copy", from: project.assetsDir });
+export const buildFilmProject = Effect.fn("buildFilmProject")(function* (project, dir, options = {}) {
+    const built = yield* buildInMemory(project, { ...options, portable: true });
+    yield* writeBuildFiles(dir, built.build, { kind: "copy", from: built.assetsDir });
     const out = { ...built, dir };
     return out;
 });
 /** Builds a film project for Tongue's own use (stills, renders, dev): kept in .tongue/builds. */
-export const buildForWork = Effect.fn("buildForWork")(function* (project) {
-    const built = yield* buildInMemory(project);
-    const out = { ...built, dir: yield* keepBuild(project, built.build) };
+export const buildForWork = Effect.fn("buildForWork")(function* (project, options = {}) {
+    const built = yield* buildInMemory(project, options);
+    const out = { ...built, dir: yield* keepBuild({ ...project, assetsDir: built.assetsDir }, built.build) };
     return out;
 });

package/dist/check.d.ts

@@ -1,5 +1,6 @@
 import type { PlanSummary } from "@tongue-core/film";
 import { Effect } from "effect";
+import { type OpenOptions } from "./project.js";
 export interface CheckProblem {
     /** layout, compile, load, timeline, doc (film.json), asset. */
     readonly kind: string;
@@ -15,4 +16,4 @@ export interface CheckReport {
     readonly summary: PlanSummary | null;
     readonly text: string | null;
 }
-export declare const checkFilm: (path: string) => Effect.Effect<CheckReport, import("./errors.js").InvalidRequest | import("./errors.js").ToolFailure | import("effect/Config").ConfigError | import("effect/PlatformError").PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("effect/FileSystem").FileSystem | import("effect/Path").Path>;
+export declare const checkFilm: (path: string, options?: OpenOptions | undefined) => Effect.Effect<CheckReport, import("./errors.js").InvalidRequest | import("./errors.js").ToolFailure | import("effect/Config").ConfigError | import("effect/PlatformError").PlatformError | import("effect/Schema").SchemaError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("effect/FileSystem").FileSystem | import("effect/Path").Path>;

package/dist/check.js

@@ -1,13 +1,14 @@
 import { Effect } from "effect";
 import { describeFilm, openFilm } from "./project.js";
 const failed = (problems) => ({ ok: false, problems, warnings: [], summary: null, text: null });
-export const checkFilm = Effect.fn("checkFilm")(function* (path) {
-    return yield* openFilm(path).pipe(Effect.map((film) => {
+export const checkFilm = Effect.fn("checkFilm")(function* (path, options = {}) {
+    return yield* openFilm(path, options).pipe(Effect.map((film) => {
         const { text, summary } = describeFilm(film);
         return { ok: true, problems: [], warnings: film.plan.warnings, summary, text };
     }), Effect.catchTags({
         FilmFailure: (e) => Effect.succeed(failed([{ kind: e.phase === "load" ? "load" : "timeline", file: e.film, message: e.message }])),
         AssetFailure: (e) => Effect.succeed(failed([{ kind: "asset", file: null, message: e.message }])),
+        MediaFailure: (e) => Effect.succeed(failed([{ kind: "asset", file: null, message: e.message }])),
         LayoutError: (e) => Effect.succeed(failed(e.problems.map((p) => ({ kind: "layout", file: p.file, message: p.message })))),
         CompileError: (e) => Effect.succeed(failed([{ kind: "compile", file: e.line === null ? e.file : `${e.file}:${e.line}`, message: e.message }])),
         LoadError: (e) => Effect.succeed(failed([{ kind: "load", file: e.file, message: e.message }])),

package/dist/client.d.ts

@@ -2,7 +2,10 @@ import { type InitOptions } from "./init.js";
 import { type OpenOptions } from "./project.js";
 import { type VideoOptions } from "./render/pipeline.js";
 import { type StillsOptions } from "./render/stills.js";
-export declare function createTongue(): {
+import type { MediaOptions } from "./media/cache.js";
+export declare function createTongue(configuration?: {
+    readonly media?: MediaOptions;
+}): {
     /** Makes a film project in a new or empty folder from a template. */
     init: (dir: string, options?: InitOptions) => Promise<import("./init.js").InitReport>;
     /** The templates that come with Tongue. */
@@ -18,6 +21,7 @@ export declare function createTongue(): {
     /** Builds a film project: build.json, film.json and a bundle per scene, in its dist folder. */
     build: (project: string, options?: {
         readonly out?: string;
+        readonly media?: MediaOptions;
     }) => Promise<import("./index.js").BuiltProject>;
     /** Imports the film's assets and plans it; resolves to its timeline as text and JSON. */
     info: (film: string) => Promise<{

package/dist/client.js

@@ -14,24 +14,24 @@ const run = async (effect) => {
         return exit.value;
     throw Cause.squash(exit.cause);
 };
-export function createTongue() {
+export function createTongue(configuration = {}) {
     return {
         /** Makes a film project in a new or empty folder from a template. */
         init: (dir, options) => run(initProject(dir, options)),
         /** The templates that come with Tongue. */
         templates: () => run(listTemplates()),
         /** Builds a film project: build.json, film.json and a bundle per scene, in its dist folder. */
-        build: (project, options) => run(buildFilm(project, options)),
+        build: (project, options) => run(buildFilm(project, { media: configuration.media, ...options })),
         /** Imports the film's assets and plans it; resolves to its timeline as text and JSON. */
-        info: (film) => run(openFilm(film).pipe(Effect.map(describeFilm))),
+        info: (film) => run(openFilm(film, configuration).pipe(Effect.map(describeFilm))),
         /** Problems and warnings as data: never rejects for a broken film. */
-        check: (film) => run(checkFilm(film)),
+        check: (film) => run(checkFilm(film, configuration)),
         /** Frames as PNG files. */
-        stills: (film, options) => run(openFilm(film, options).pipe(Effect.flatMap((f) => renderStills(f, options)))),
+        stills: (film, options) => run(openFilm(film, { ...configuration, ...options }).pipe(Effect.flatMap((f) => renderStills(f, options)))),
         /** Frames tiled into one labelled image. */
-        sheet: (film, options) => run(openFilm(film, options).pipe(Effect.flatMap((f) => renderSheet(f, options)))),
+        sheet: (film, options) => run(openFilm(film, { ...configuration, ...options }).pipe(Effect.flatMap((f) => renderSheet(f, options)))),
         /** The film (or a range of it, or one scene of a project) as an MP4. */
-        render: (film, options) => run(openFilm(film, options).pipe(Effect.flatMap((f) => renderVideo(f, options)))),
+        render: (film, options) => run(openFilm(film, { ...configuration, ...options }).pipe(Effect.flatMap((f) => renderVideo(f, options)))),
         /** The rasters and encoders this machine can use. */
         backends: () => run(listBackends()),
     };

package/dist/encode/encoders.js

@@ -2,7 +2,7 @@
 // (VAAPI on AMD and Intel under Linux, NVENC on NVIDIA, Quick Sync on Intel) differ only in the
 // arguments around the input. `available()` runs a short encode through the exact same arguments,
 // so it proves the ffmpeg build, the device and the driver all work. Plain TypeScript: encoders run
-// in the render loop. The settings are the ones measured in docs/render-pipeline.md.
+// in the render loop. The settings are the ones measured in docs/render-performance.md.
 export class EncoderError extends Error {
     name = "EncoderError";
 }
@@ -94,7 +94,7 @@ export async function encoderWorks(ffmpeg, spec, size = { width: 320, height: 24
 }
 export const DEFAULT_SETTINGS = { preset: "veryfast", crf: 14, threads: 2, qp: null, gop: null, x264Params: "" };
 export const X264_PRESETS = ["ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow"];
-/** Constant QP that clears the master-quality bar on our films (see docs/render-pipeline.md). */
+/** Constant QP that clears the master-quality bar on our films. */
 const HARDWARE_QP = { h264: 16, hevc: 18 };
 const profile = (codec) => (codec === "hevc" ? "main" : "high");
 const vaapiDevice = () => process.env["TONGUE_VAAPI_DEVICE"] ?? "/dev/dri/renderD128";

package/dist/errors.d.ts

@@ -1,5 +1,6 @@
 import { CompileError, DocError, LayoutError, LoadError, TemplateError, TimelineError } from "@tongue-core/project";
 import { Schema } from "effect";
+import { MediaFailure } from "@tongue-core/project/media";
 declare const FilmFailure_base: Schema.Class<FilmFailure, Schema.TaggedStruct<"FilmFailure", {
     readonly film: Schema.String;
     /** "load" (the module threw or isn't there), "film" (not a <Film>, or the timeline is wrong). */
@@ -54,9 +55,9 @@ declare const ProcessorFailure_base: Schema.Class<ProcessorFailure, Schema.Tagge
  *  channels, another length) or isn't audio (a sample that isn't a finite number). */
 export declare class ProcessorFailure extends ProcessorFailure_base {
 }
-export declare const SdkError: Schema.Union<readonly [typeof FilmFailure, typeof AssetFailure, typeof InvalidRequest, typeof ToolFailure, typeof BackendUnavailable, typeof RenderFailure, typeof ProcessorFailure, typeof LayoutError, typeof CompileError, typeof LoadError, typeof TimelineError, typeof DocError, typeof TemplateError]>;
+export declare const SdkError: Schema.Union<readonly [typeof FilmFailure, typeof AssetFailure, typeof InvalidRequest, typeof ToolFailure, typeof BackendUnavailable, typeof RenderFailure, typeof ProcessorFailure, typeof MediaFailure, typeof LayoutError, typeof CompileError, typeof LoadError, typeof TimelineError, typeof DocError, typeof TemplateError]>;
 export type SdkError = typeof SdkError.Type;
-export declare const isSdkError: <I>(input: I) => input is I & (FilmFailure | AssetFailure | InvalidRequest | ToolFailure | BackendUnavailable | RenderFailure | ProcessorFailure | LayoutError | CompileError | LoadError | TimelineError | DocError | TemplateError);
+export declare const isSdkError: <I>(input: I) => input is I & (FilmFailure | AssetFailure | InvalidRequest | ToolFailure | BackendUnavailable | RenderFailure | ProcessorFailure | MediaFailure | LayoutError | CompileError | LoadError | TimelineError | DocError | TemplateError);
 /** Exhaustive: a new error without a case is a compile error. */
 export declare function exitCodeOf(error: SdkError): number;
 /** The message of anything thrown. */

package/dist/errors.js

@@ -1,5 +1,6 @@
 import { CompileError, DocError, LayoutError, LoadError, TemplateError, TimelineError } from "@tongue-core/project";
 import { Schema } from "effect";
+import { MediaFailure } from "@tongue-core/project/media";
 // Every way the SDK can fail, as tagged errors with a message an agent (or a person) can act on.
 // `exitCodeOf` maps each to the CLI's exit code: 2 when the input is wrong (fix the film or the
 // arguments), 3 when the machine is (a missing tool, a device, a crash). Building a film project
@@ -52,7 +53,7 @@ export class ProcessorFailure extends Schema.TaggedError()("ProcessorFailure", {
 }) {
 }
 export const SdkError = Schema.Union([
-    FilmFailure, AssetFailure, InvalidRequest, ToolFailure, BackendUnavailable, RenderFailure, ProcessorFailure,
+    FilmFailure, AssetFailure, InvalidRequest, ToolFailure, BackendUnavailable, RenderFailure, ProcessorFailure, MediaFailure,
     LayoutError, CompileError, LoadError, TimelineError, DocError, TemplateError,
 ]);
 export const isSdkError = Schema.is(SdkError);
@@ -60,6 +61,7 @@ export const isSdkError = Schema.is(SdkError);
 export function exitCodeOf(error) {
     switch (error._tag) {
         case "FilmFailure":
+        case "MediaFailure":
         case "AssetFailure":
         case "InvalidRequest":
         case "LayoutError":

package/dist/import/convert.js

@@ -11,9 +11,11 @@ export function fontToTtf(bytes) {
 }
 /** Decodes the image formats the engine reads itself; null for the rest (ffmpeg decodes those). */
 export function decodeImage(bytes, extension) {
-    if (extension === ".png")
+    const png = bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71;
+    const jpeg = bytes[0] === 255 && bytes[1] === 216;
+    if (png || extension === ".png")
         return decodePng(bytes, (z) => new Uint8Array(inflateSync(z)));
-    if (extension === ".jpg" || extension === ".jpeg")
+    if (jpeg || extension === ".jpg" || extension === ".jpeg")
         return decodeJpeg(bytes);
     return null;
 }

package/dist/import/importer.d.ts

@@ -1,11 +1,26 @@
 import type { Asset } from "@tongue-core/film";
 import { Effect, FileSystem, Path } from "effect";
-import { AssetFailure } from "../errors.js";
 import type { Project } from "../project.js";
-export interface ImportReport {
-    readonly imported: ReadonlyArray<string>;
-    readonly skipped: ReadonlyArray<string>;
-    /** Media lengths in seconds, by `kind:name`. */
-    readonly durations: ReadonlyMap<string, number>;
-}
-export declare const importAssets: (project: Project, assets: readonly Asset[]) => Effect.Effect<ImportReport, AssetFailure | import("../errors.js").ToolFailure | import("effect/Config").ConfigError | import("effect/PlatformError").PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | Path.Path>;
+import { type MediaOptions } from "../media/cache.js";
+export type { ImportReport } from "./types.js";
+/** Both source kinds converge on the engine's virtual asset paths. */
+export declare const importAssets: (project: Project, assets: readonly Asset[], configuration?: (MediaOptions & {
+    readonly portable?: boolean;
+}) | undefined) => Effect.Effect<{
+    imported: string[];
+    skipped: string[];
+    durations: Map<string, number>;
+    remoteFiles: {
+        readonly path: string;
+        readonly bytes: number;
+        readonly hash: string;
+        readonly url?: string | undefined;
+    }[];
+    originals: {
+        readonly kind: "font" | "image" | "audio" | "video";
+        readonly name: string;
+        readonly source: string;
+        readonly hash: string;
+        readonly bytes: number;
+    }[];
+}, import("../errors.js").AssetFailure | import("../errors.js").ToolFailure | import("@tongue-core/project/media").MediaFailure | import("effect/Config").ConfigError | import("effect/PlatformError").PlatformError | import("effect/Schema").SchemaError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | Path.Path>;

package/dist/import/importer.js

@@ -1,96 +1,30 @@
-import { importedPath, videoPosterPath, videoProxyDir } from "@tongue-core/engine";
-import { Effect, FileSystem, Path, Schema } from "effect";
-import { AssetFailure, messageOf } from "../errors.js";
-import { decodeImage, fontToTtf, imageToQoi } from "./convert.js";
-import { audioToWav, imageViaFfmpeg, importVideo, makeProxy, probeMedia, proxyInfo } from "./media.js";
-// Importing: every asset a film declares, turned into what the engine reads (TrueType fonts, QOI
-// images, WAV audio, video facts, posters and proxies) under .tongue/assets. A manifest remembers each
-// source's size, modified time and options, so unchanged assets are skipped.
-const Entry = Schema.Struct({
-    fingerprint: Schema.String,
-    /** Seconds, for audio and video. */
-    duration: Schema.optional(Schema.Number),
-});
-const Manifest = Schema.Struct({ version: Schema.Literal(1), assets: Schema.Record(Schema.String, Entry) });
-const decodeManifest = Schema.decodeUnknownEffect(Schema.fromJsonString(Manifest));
-const keyOf = (asset) => `${asset.kind}:${asset.name}`;
-/** What else an import depends on: a different size, or proxies made a new way, imports again. */
-const PROXY_VERSION = 2;
-const optionsOf = (asset) => (asset.kind === "image" ? `max${asset.maxSize}` : asset.kind === "video" ? `max${asset.maxSize};proxy${PROXY_VERSION}` : "");
-export const importAssets = Effect.fn("importAssets")(function* (project, assets) {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const manifestPath = path.join(project.assetsDir, "manifest.json");
-    const empty = { version: 1, assets: {} };
-    const previous = yield* fs.readFileString(manifestPath).pipe(Effect.flatMap(decodeManifest), Effect.orElseSucceed(() => empty));
-    const write = Effect.fn("write")(function* (relative, bytes) {
-        const target = path.join(project.assetsDir, relative);
-        yield* fs.makeDirectory(path.dirname(target), { recursive: true });
-        yield* fs.writeFile(target, bytes);
-    });
-    const results = yield* Effect.forEach(assets, (asset) => Effect.gen(function* () {
-        const key = keyOf(asset);
-        const source = path.resolve(project.root, asset.source);
-        const stat = yield* fs.stat(source).pipe(Effect.mapError(() => new AssetFailure({ asset: key, message: `${asset.kind} "${asset.name}": no file at ${asset.source} (relative to ${project.root}).` })));
-        const modified = stat.mtime._tag === "Some" ? stat.mtime.value.getTime() : 0;
-        const fingerprint = `${Number(stat.size)}:${modified}:${optionsOf(asset)}`;
-        const known = previous.assets[key];
-        const output = path.join(project.assetsDir, importedPath(asset));
-        if (known?.fingerprint === fingerprint && (yield* fs.exists(output).pipe(Effect.orElseSucceed(() => false)))) {
-            return { key, entry: known, imported: false };
-        }
-        const read = fs.readFile(source).pipe(Effect.mapError((e) => new AssetFailure({ asset: key, message: `Could not read ${source}: ${e.message}` })));
-        const convert = (run) => Effect.try({ try: run, catch: (e) => new AssetFailure({ asset: key, message: `${asset.kind} "${asset.name}" (${asset.source}): ${messageOf(e)}` }) });
-        let duration;
-        switch (asset.kind) {
-            case "font": {
-                const bytes = yield* read;
-                yield* write(importedPath(asset), yield* convert(() => fontToTtf(bytes)));
-                break;
-            }
-            case "image": {
-                const bytes = yield* read;
-                const decoded = yield* Effect.try({ try: () => decodeImage(bytes, path.extname(source).toLowerCase()), catch: (e) => new AssetFailure({ asset: key, message: `${asset.source}: ${messageOf(e)}` }) });
-                const image = decoded ?? (yield* imageViaFfmpeg(key, source));
-                yield* write(importedPath(asset), yield* convert(() => imageToQoi(image, asset.maxSize)));
-                break;
-            }
-            case "audio": {
-                duration = (yield* probeMedia(key, source)).duration;
-                yield* write(importedPath(asset), yield* audioToWav(source));
-                break;
-            }
-            case "video": {
-                const video = yield* importVideo(key, source, asset.maxSize);
-                duration = video.duration;
-                // The proxy, made fresh into its folder; its segments' facts go into info.json.
-                const proxyDir = path.join(project.assetsDir, videoProxyDir(asset));
-                yield* fs.remove(proxyDir, { recursive: true, force: true });
-                yield* fs.makeDirectory(proxyDir, { recursive: true });
-                yield* makeProxy(source, video.info, proxyDir).pipe(Effect.mapError((e) => new AssetFailure({ asset: key, message: `video "${asset.name}": its proxy couldn't be made: ${e.message}` })));
-                const names = (yield* fs.readDirectory(proxyDir)).filter((n) => n.endsWith(".mp4")).sort();
-                const segments = yield* Effect.forEach(names, (n) => fs.readFile(path.join(proxyDir, n)));
-                const proxy = yield* proxyInfo(asset.name, segments);
-                // The facts and the proxy only: never the source's absolute path, which names this
-                // machine and is wrong on any other (renders find the source themselves, see videoInputs).
-                yield* write(importedPath(asset), new TextEncoder().encode(JSON.stringify({ ...video.info, proxy })));
-                yield* write(videoPosterPath(asset), video.poster);
-                break;
-            }
-        }
-        return { key, entry: duration === undefined ? { fingerprint } : { fingerprint, duration }, imported: true };
-    }), { concurrency: 4 });
-    const manifest = { version: 1, assets: Object.fromEntries(results.map((r) => [r.key, r.entry])) };
-    yield* fs.makeDirectory(project.assetsDir, { recursive: true });
-    yield* fs.writeFileString(manifestPath, JSON.stringify(manifest, null, 2));
-    const durations = new Map();
-    for (const r of results)
-        if (r.entry.duration !== undefined)
-            durations.set(r.key, r.entry.duration);
-    const report = {
-        imported: results.filter((r) => r.imported).map((r) => r.key),
-        skipped: results.filter((r) => !r.imported).map((r) => r.key),
-        durations,
+import { isRemoteSource } from "@tongue-core/project/media";
+import { Effect, FileSystem, Path } from "effect";
+import { importRemoteAsset } from "../media/prepare.js";
+import { mediaOptions } from "../media/cache.js";
+import { decodeImportManifest, importLocalAssets } from "./local.js";
+/** Both source kinds converge on the engine's virtual asset paths. */
+export const importAssets = Effect.fn("importAssets")(function* (project, assets, configuration = {}) {
+    const options = mediaOptions(configuration);
+    const local = yield* importLocalAssets(project, assets.filter((asset) => !isRemoteSource(asset.source)));
+    const remote = yield* Effect.forEach(assets.filter((asset) => isRemoteSource(asset.source)), (asset) => importRemoteAsset(project, asset, options, configuration.portable ?? false), { concurrency: options.concurrency ?? 4 });
+    const durations = new Map(local.durations);
+    for (const item of remote)
+        if (item.duration !== undefined)
+            durations.set(item.key, item.duration);
+    if (remote.length > 0) {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const file = path.join(project.assetsDir, "manifest.json");
+        const manifest = yield* fs.readFileString(file).pipe(Effect.flatMap(decodeImportManifest));
+        const entries = { ...manifest.assets };
+        for (const item of remote)
+            entries[item.key] = { fingerprint: `remote:${item.original.hash}`, ...(item.duration === undefined ? {} : { duration: item.duration }) };
+        yield* fs.writeFileString(file, JSON.stringify({ version: 1, assets: entries }, null, 2));
+    }
+    return {
+        imported: [...local.imported, ...remote.filter((item) => !item.cached).map((item) => item.key)],
+        skipped: [...local.skipped, ...remote.filter((item) => item.cached).map((item) => item.key)],
+        durations, remoteFiles: remote.flatMap((item) => item.files), originals: remote.map((item) => item.original),
     };
-    return report;
 });

package/dist/import/local.d.ts

@@ -0,0 +1,17 @@
+import type { ImportReport } from "./types.js";
+import type { Asset } from "@tongue-core/film";
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { AssetFailure } from "../errors.js";
+import type { Project } from "../project.js";
+export declare const decodeImportManifest: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => Effect.Effect<{
+    readonly version: 1;
+    readonly assets: {
+        readonly [x: string]: {
+            readonly fingerprint: string;
+            readonly duration?: number | undefined;
+        };
+    };
+}, Schema.SchemaError, never>;
+/** What else an import depends on: a different size, or proxies made a new way, imports again. */
+export declare const PROXY_VERSION = 2;
+export declare const importLocalAssets: (project: Project, assets: readonly Asset[]) => Effect.Effect<ImportReport, AssetFailure | import("../errors.js").ToolFailure | import("effect/Config").ConfigError | import("effect/PlatformError").PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | Path.Path>;