@gentbajko/slopify 3.25.9 → 4.1.0

package/dist/slices/video/write-export.js

@@ -1,158 +0,0 @@
-import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { dirname } from "node:path";
-import { transact } from "../../kernel/db/tx.js";
-import { setStageProgress } from "../admission/stage-writes.js";
-import { outputPath } from "../storage/layout.js";
-import { deleteOutput, insertOutput, outputsOf } from "../storage/repo.js";
-import { subtitleRoles } from "../subtitles/prepare.js";
-const progressIntervalMs = 500;
-const renderRoles = [
-    "video",
-    "audio_export",
-    "render_params",
-    ...subtitleRoles,
-];
-// Both local exports retain the previous finished asset until ffmpeg succeeds and
-// the abort check passes. The part file keeps its muxer's filename extension.
-export async function writeExport(deps, context, output) {
-    const { projectId } = context.stage;
-    const target = outputPath(deps.paths, projectId, output.filename);
-    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
-    // The plan is the record of what was rendered and names the file the user downloads,
-    // so it keeps the final path; only the ffmpeg invocation is pointed at the part file.
-    const part = outputPath(deps.paths, projectId, output.partName);
-    const totalMs = Math.round(output.totalSeconds * 1000);
-    let announced = 0;
-    try {
-        // No retry and no timeout. A render that fails is terminal.
-        await output.render(part, (elapsedMs) => {
-            const at = deps.clock.now().getTime();
-            if (at - announced < progressIntervalMs) {
-                return;
-            }
-            announced = at;
-            const current = output.subtitles === undefined
-                ? Math.min(elapsedMs, totalMs)
-                : Math.round((0.35 + 0.65 * Math.min(elapsedMs / totalMs, 1)) * totalMs);
-            setStageProgress(deps.db, context.stage.id, current, totalMs);
-            context.emit({
-                type: "stage.progress",
-                projectId,
-                stage: "video",
-                current,
-                total: totalMs,
-            });
-        });
-        // A cancel protects an output that was already stored, not one about to be. One
-        // landing between ffmpeg exiting and the rows below discards the render rather than
-        // reporting done to a page that pressed Cancel.
-        context.signal.throwIfAborted();
-    }
-    catch (error) {
-        // A partial render file is discarded, never kept or served. Only the part file: the
-        // previous export is a finished output and stays downloadable.
-        rmSync(part, { force: true });
-        if (output.subtitles !== undefined)
-            rmSync(output.subtitles.directory, { recursive: true, force: true });
-        throw error;
-    }
-    const params = outputPath(deps.paths, projectId, "render.json");
-    const previousOutputs = outputsOf(deps.db, projectId);
-    const replaced = [];
-    const paramsPart = outputPath(deps.paths, projectId, "render.part.json");
-    let committed = false;
-    try {
-        writeFileSync(paramsPart, `${JSON.stringify(output.record, null, 2)}\n`, { mode: 0o600 });
-        // The DB commit can fail after ffmpeg succeeds. Keep rollback copies until all
-        // media, caption and font rows commit, so a failed export keeps its old playback.
-        for (const path of [target, params]) {
-            const saved = { path, backup: `${path}.previous`, existed: existsSync(path), swapped: false };
-            if (saved.existed)
-                copyFileSync(path, saved.backup);
-            replaced.push(saved);
-        }
-        for (const saved of replaced) {
-            renameSync(saved.path === target ? part : paramsPart, saved.path);
-            saved.swapped = true;
-        }
-        transact(deps.db, () => {
-            for (const previous of previousOutputs) {
-                if (renderRoles.includes(previous.role))
-                    deleteOutput(deps.db, previous.id);
-            }
-            store(deps, projectId, "render_params", "render.json", null);
-            store(deps, projectId, output.role, output.filename, totalMs, {
-                ...(output.subtitles?.omissions?.length
-                    ? { subtitleOmissions: output.subtitles.omissions }
-                    : {}),
-                subtitlesMode: output.subtitles === undefined ? "off" : output.subtitles.burnIn ? "burn-in" : "files",
-            });
-            for (const asset of output.subtitles?.assets ?? [])
-                store(deps, projectId, asset.role, asset.path, null);
-        });
-        committed = true;
-    }
-    catch (error) {
-        for (const saved of replaced) {
-            if (!saved.swapped)
-                continue;
-            if (saved.existed)
-                renameSync(saved.backup, saved.path);
-            else
-                rmSync(saved.path, { force: true });
-            saved.swapped = false;
-        }
-        rmSync(part, { force: true });
-        rmSync(paramsPart, { force: true });
-        if (output.subtitles !== undefined)
-            rmSync(output.subtitles.directory, { recursive: true, force: true });
-        throw error;
-    }
-    finally {
-        for (const saved of replaced) {
-            if (!committed && saved.swapped)
-                continue;
-            try {
-                rmSync(saved.backup, { force: true });
-            }
-            catch {
-                /* A retained backup is collected at the next boot. */
-            }
-        }
-    }
-    const kept = new Set(outputsOf(deps.db, projectId).map((one) => one.path));
-    for (const previous of previousOutputs) {
-        if (renderRoles.includes(previous.role) && !kept.has(previous.path)) {
-            try {
-                rmSync(outputPath(deps.paths, projectId, previous.path), { force: true });
-            }
-            catch {
-                /* Boot reconciliation collects a file that could not be removed. */
-            }
-        }
-    }
-    // Written as well as emitted: a page opened after the render reads the row, and the
-    // throttled in-flight writes would have left it frozen short of the end.
-    setStageProgress(deps.db, context.stage.id, totalMs, totalMs);
-    context.emit({
-        type: "stage.progress",
-        projectId,
-        stage: "video",
-        current: totalMs,
-        total: totalMs,
-    });
-}
-function store(deps, projectId, role, path, durationMs, meta = {}) {
-    insertOutput(deps.db, {
-        id: deps.ids.next(),
-        projectId,
-        stageKind: "video",
-        role,
-        path,
-        originalFilename: null,
-        bytes: statSync(outputPath(deps.paths, projectId, path)).size,
-        durationMs,
-        meta,
-        createdAt: deps.clock.now().toISOString(),
-    });
-}

package/dist/slices/video/write-subtitles.js

@@ -1,59 +0,0 @@
-import { rmSync, statSync } from "node:fs";
-import { transact } from "../../kernel/db/tx.js";
-import { setStageProgress } from "../admission/stage-writes.js";
-import { outputPath } from "../storage/layout.js";
-import { deleteOutput, insertOutput, outputsOf } from "../storage/repo.js";
-import { subtitleRoles } from "../subtitles/prepare.js";
-// Commit sidecars and subtitle metadata without opening, copying or replacing the WAV.
-export function writeSubtitles(deps, context, media, subtitles) {
-    const projectId = context.stage.projectId;
-    const previous = outputsOf(deps.db, projectId).filter((output) => subtitleRoles.some((role) => role === output.role));
-    const { subtitleOmissions: _oldOmissions, subtitlesMode: _oldMode, ...keptMeta } = media.meta;
-    const meta = {
-        ...keptMeta,
-        subtitlesMode: subtitles === undefined ? "off" : "files",
-        ...(subtitles?.omissions?.length ? { subtitleOmissions: subtitles.omissions } : {}),
-    };
-    try {
-        context.emit({ type: "stage.progress", projectId, stage: "video", current: 99, total: 100 });
-        context.signal.throwIfAborted();
-        transact(deps.db, () => {
-            for (const output of previous)
-                deleteOutput(deps.db, output.id);
-            deps.db
-                .prepare("UPDATE outputs SET meta = ? WHERE id = ?")
-                .run(JSON.stringify(meta), media.id);
-            for (const asset of subtitles?.assets ?? [])
-                insertOutput(deps.db, {
-                    id: deps.ids.next(),
-                    projectId,
-                    stageKind: "video",
-                    role: asset.role,
-                    path: asset.path,
-                    originalFilename: null,
-                    bytes: statSync(outputPath(deps.paths, projectId, asset.path)).size,
-                    durationMs: null,
-                    meta: {},
-                    createdAt: deps.clock.now().toISOString(),
-                });
-        });
-    }
-    catch (error) {
-        if (subtitles !== undefined)
-            rmSync(subtitles.directory, { recursive: true, force: true });
-        throw error;
-    }
-    const kept = new Set((subtitles?.assets ?? []).map((asset) => asset.path));
-    for (const output of previous) {
-        if (kept.has(output.path))
-            continue;
-        try {
-            rmSync(outputPath(deps.paths, projectId, output.path), { force: true });
-        }
-        catch {
-            /* Boot reconciliation collects obsolete files still held by a player. */
-        }
-    }
-    setStageProgress(deps.db, context.stage.id, 100, 100);
-    context.emit({ type: "stage.progress", projectId, stage: "video", current: 100, total: 100 });
-}

package/dist/tutorials/Library-Overview.md

@@ -1,76 +0,0 @@
-# Library Overview
-
-The Library holds the reusable pieces your videos are made from: prompts, intros and outros, templates, PDF document themes and narration aliases. Write a piece once and pick it on Play for every video that needs it.
-
-**Where to find it:** **Library** in the sidebar. It opens on **Prompts**; the tabs across the top switch sections. They come in three groups: **Setups** (what a project starts from), **Building blocks** (what those setups are made of) and **Results**.
-
-## The tabs
-
-| Group | Tab | What it holds | Page |
-|---|---|---|---|
-| Setups | **Templates** | Saved Play setups, and **Add pack** for the starter packs | [Templates](Templates) |
-| Building blocks | **Prompts** | The instructions for articles, images, thumbnails, narration cues, YouTube descriptions, shorts, reviews and multi-voice scripts, each with `{{keywords}}` where the subject goes | [Prompts](Prompts) |
-| Building blocks | **Intros & outros** | Short narrated openings and closings, written as text or generated by the text model | [Intros and outros](Intros-and-Outros) |
-| Building blocks | **PDF themes** | Document themes: the look of the PDF made from the article | [Document themes](Document-Themes) |
-| Building blocks | **Narration aliases** | Words the narrator says differently from how they are written, such as Dr. as Doctor | [Aliases and glossary](Narration-Aliases-and-Glossary) |
-| Results | **A/B results** | How the versions of an A/B test did | |
-
-## What every Library list has
-
-Prompts, Intros & outros and Templates share the same row actions, in the same order:
-
-| Action | What it does |
-|---|---|
-| **Edit** | Opens the item in its editor. (A template has no editor: Edit picks it and shows its keywords beside the list.) |
-| **Duplicate** | Opens the editor with a copy, for you to rename and save. (A template is copied as `<name> copy` at once.) |
-| **Use in Play** | Picks the item in your open Play draft and opens Play on the field that shows it. An article prompt switches the article to Generate, an image prompt is ticked with one image, a thumbnail prompt switches the thumbnail to From prompt, and a Description or Shorts prompt turns that step on. The rest of the draft stays as it was. The button is off while Play is starting a run. |
-| **History** | Opens the item's versions, a side-by-side compare, and what uses it. See [Prompts](Prompts#history-and-versions). |
-| **Delete** | Asks first, then moves the item to **Settings → Backup & storage → Trash** for 30 days. See [Trash](Trash). |
-
-Your document themes have Edit, Duplicate and Delete, but no Use in Play or History. Built-in themes can only be copied.
-
-A press anywhere on a row picks it; the row's own buttons still do their own thing. Beside each list, the selected item shows its text, its **Keywords**, what it is **Used by**, and its latest change.
-
-### Rename in the row
-
-In Prompts, Intros & outros and Templates, the pencil beside a name (**Rename <name>**) turns the name into a field. Type the new name and press **Save name** or Enter; `Esc` or **Cancel** keeps the old one. Only the name changes, and the notice ("Renamed “A” to “B”.") has **Undo**. A prompt's or entry's rename is one History version; a template's is a new template version.
-
-### Save with Ctrl+S
-
-In the prompt, intro and outro and document theme editors, `Ctrl+S` (`Cmd+S`) saves, even while you are typing in a field.
-
-## Search and filter
-
-- **Prompts** has a **Prompt kind** picker (Article, Image, Thumbnail, Narration Preparation, YouTube Description, Shorts, Review, Script (speakers)) and **Search prompts**.
-- **Intros & outros** has **Search intros and outros**.
-- **Templates** has **Show templates of** to filter by channel.
-- Press `/` on Prompts or Intros & outros to jump to the search box.
-
-## Command palette shortcuts
-
-Press `Ctrl+K` anywhere and type to find **New prompt**, **New intro or outro**, **New PDF theme**, **Open prompts**, **Open intros and outros**, **Open templates** or **Open PDF themes**, or a saved item by name: **Open template <name>** (Templates with it shown beside the list), **Edit prompt <name>**, **Edit intro <name>** / **Edit outro <name>** and **Edit PDF theme <name>**. See [Keyboard and Ctrl+K](Keyboard-Shortcuts-and-Command-Palette).
-
-## Starter packs
-
-**Library → Templates → Add pack** adds a ready-made set for one kind of channel: prompts, a suggested voice and a Play template. There are four packs: Sleep lore, True crime, History and Science explainers. Adding one twice changes nothing, and a pack never replaces a prompt or template of yours with the same name. See [Templates](Templates#starter-packs).
-
-## Fonts
-
-The Library has no separate font manager. Fonts live where they are used:
-
-- **Caption (subtitle) fonts:** upload your own in the subtitle font picker on Play's video style settings. Uploaded fonts then appear in a channel's brand kit too. See [Video and style](Play-Video-and-Style) and [Channels](Channels).
-- **PDF fonts:** each document theme picks its fonts from the bundled Cinzel and the fonts built into every PDF reader (Times, Helvetica, Courier). See [Document themes](Document-Themes).
-
-Uploaded fonts travel in backups, but templates leave them out.
-
-## How changes reach your videos
-
-A project copies the prompts, intros, outros, aliases and theme settings it uses when it starts. Editing the Library later changes only runs started afterwards. Templates also keep their own copies, so save a template again to pick up a changed prompt. In a project, **Edit project** shows the project's own copy of each prompt: pick the Library prompt again (or press **Use the Library version**) to bring in your latest edit, and press **Update from Library** under narration aliases to copy the current alias list. See [Editing a project](Editing-a-Project).
-
-## Related pages
-
-- [Prompts](Prompts)
-- [Intros and outros](Intros-and-Outros)
-- [Templates](Templates)
-- [Document themes](Document-Themes)
-- [Aliases and glossary](Narration-Aliases-and-Glossary)

package/dist/tutorials/Play-Images.md

@@ -1,161 +0,0 @@
-# Play Images
-
-The images are the pictures your video shows while the narration plays. On Play you pick who draws them, which Library image prompts they come from and how many each makes, and optionally an establishing image that keeps characters and style consistent. You get a set of images, drawn in the video's frame shape, played in order.
-
-**Where to find it:** Play → **Images** row → **Change**.
-
-## Choose where the images come from
-
-The Images row starts with a **Source** switch:
-
-| Source | What happens | Cost |
-| --- | --- | --- |
-| **Generate** (default) | Draws images from the ticked image prompts, one image-model call each. | Per image, by the provider |
-| **Provide** | Uses your own PNG, JPEG or WebP files (**Slideshow images**) in the order you pick them. | None |
-| **Off** | No images. This turns the video off too: the **Video and style** row says "Video is Off because Images is Off." | None |
-
-### Use your own images
-
-1. Set **Source** to **Provide**.
-2. Pick the files under **Slideshow images**. Each is numbered in the order it plays.
-3. Remove a file with its remove button, or reattach one whose upload was lost.
-
-A video can have at most 60 of your images, and the same file cannot be picked twice. Wait for every upload to finish before pressing Start.
-
-## Pick the image provider and model
-
-| Option | What it does | Default |
-| --- | --- | --- |
-| **Provider** | Who draws the images, the thumbnail and the shorts' pictures: a keyed service billed per image (fal.ai, Replicate, OpenAI, Google), or a command-line tool you are signed in to (Codex CLI). A greyed provider says why it cannot be used; fix it under Settings. | Your Settings default |
-| **Model** | The provider's image model. Models differ in quality, speed and price per image; the estimate in the right rail shows what this run costs. The refresh button asks for the current list; **Custom ID** lets you type one. | Your Settings default |
-| **Effort** | How long an image agent, such as the Codex CLI, reasons before it draws. Higher effort can follow the prompt more closely but takes longer and uses more tokens. Shown only for models that offer levels. | **Model default** |
-
-Changing the provider clears the model.
-
-### Drawing with the Codex CLI
-
-With **Codex CLI** as the image provider, the **Model** list holds **Codex default** and the Codex CLI's own models. **Codex default** leaves the model and effort to the CLI's own defaults. Any other model runs with the **Effort** you pick. An image agent that reviews and redraws its picture can work for several minutes at a high effort. Images drawn this way cost nothing extra on your plan; the estimate shows the approximate API price beside **$0 on your plan**. See [AI CLIs](AI-CLIs).
-
-## Pick the image prompts
-
-1. Under **Image prompts**, tick the Library prompts that should draw the video's images.
-2. Give each ticked prompt a **Number**: how many images it makes, 1 to 20.
-3. Check the total under the list, for example **8 of 60 images**.
-
-| Rule | Value |
-| --- | --- |
-| Images per prompt | 1 to 20 |
-| Images per run, hand-set | at most 60 |
-| Images per run, with **More images for long videos** | at most 240 |
-| Order | The images play in the order you ticked the prompts |
-
-Each image is one image-model call. A prompt that has been deleted since this draft picked it shows **Missing template · untick to remove**. With no image prompts at all, the row says "No image prompts saved. Write one on Prompts." See [Prompts](Prompts).
-
-### Photorealistic prompts
-
-An image prompt in the Library has a **Draws photorealistic pictures** tick. Turn it on when the prompt's style looks like real photos or film. Prepare upload then answers Yes to YouTube's AI use question for videos and shorts drawn with it. Leave it off for painterly or illustrated styles. It is set on the prompt, not on Play: open Library → Prompts → the prompt. See [Prompts](Prompts) and [Publishing to YouTube](Publishing-to-YouTube).
-
-## Establishing image
-
-The establishing image is made first and never shown in the video. Every other image, the shorts' images and (if ticked) the thumbnail are drawn with it as a reference, so characters, style and palette stay the same across the video.
-
-| Option | What it does | Default |
-| --- | --- | --- |
-| **Establishing image** | **Off**, **From a prompt** (costs one more image) or **Upload** (your own PNG or JPEG, **Establishing image file**). | Off |
-| **Establishing prompt** | The Library image prompt that draws it, keywords filled like the others. Describe the characters, setting and style every other image should share. | None |
-| **Draw the thumbnail from it too** | Draws the thumbnail with the establishing image as a reference too, so it matches the video. Untick it for a thumbnail drawn on its own. | On |
-
-Changing the establishing image later marks the images drawn from it as outdated. When you upload the establishing image, the style preview in the right rail is drawn on it, so you judge the Look and captions on your own picture.
-
-### Set up an establishing image
-
-1. Under **Establishing image**, pick **From a prompt** or **Upload**.
-2. For **From a prompt**, pick the **Establishing prompt**. For **Upload**, pick the file.
-3. Leave **Draw the thumbnail from it too** ticked if the thumbnail should match.
-
-## The channel's cast
-
-The channel you pick in the **Channel** row brings its cast: characters, creatures, places and objects, each with reference pictures. When an image's brief mentions a cast member by name or alias (as a whole word, ignoring case), that image is drawn with the member's pictures as references, after the establishing image when it is on. The establishing image and the thumbnail also take the members the title mentions. At most four members go with one image.
-
-Models that take several input pictures (Codex, OpenAI, Google, and fal.ai's FLUX.2 and Nano Banana 2 edit models) use the pictures directly. A model that takes none gets the members described in words instead. The cast is used even when **Use the channel's brand kit** is off. See [Cast Library](Cast-Library) and [Channels](Channels).
-
-## More images for long videos
-
-A long video with a fixed handful of images repeats them for an hour. **More images for long videos** adds images as the narration gets longer.
-
-| Option | What it does | Default / range |
-| --- | --- | --- |
-| **More images for long videos** | Adds images, planned from the expected length when the run starts. The extra images are shared among the ticked prompts in order, up to 240 in all. Each is one more image call. | Off |
-| **How the rate is given** | **Every N minutes**: one image every N minutes of narration (0.25 to 60). **N per hour**: N images per hour (1 to 240). Switching keeps the same rate. | One image every 2 minutes |
-
-### Turn it on
-
-1. Tick at least one image prompt.
-2. Switch on **More images for long videos**.
-3. Pick **Every N minutes** or **N per hour** and type the rate.
-4. Read the line under it, for example: "For about 60 minutes (9,000 words expected, set on Review): 30 images, 26 more than the prompts' 4."
-
-How the count is worked out:
-
-- The length is the pasted article's own word count, or else **Expected article words per video** in the right rail, at 150 spoken words a minute.
-- Each ticked prompt keeps its own **Number** as a minimum. The extra images are handed to the ticked prompts one at a time, in the order they were ticked.
-- When the prompts' own Numbers already cover the length, nothing is added.
-- The count stops at 240. After that the slideshow repeats its images, as it does whenever the narration outlasts them.
-- The count is planned once, when the run starts. A narration that turns out longer is still covered by the slideshow cycling its images.
-
-Turning it on also switches **Motion** (in the **Video and style** row) from **Zoom in and out** to **Mix of both**, so a long video pans and zooms by turns. A **Pan across** or **Still** you picked stays, and you can pick Zoom again.
-
-## Scenes from the article
-
-Without it, every image of a prompt is drawn from the same text, so three images of one prompt tend to show the same picture three times. **Scenes from the article** gives every image its own moment.
-
-| Option | What it does | Default |
-| --- | --- | --- |
-| **Scenes from the article** | Before the images are drawn, the project's AI model reads the article once and writes a short scene for each image. Scene 1 comes from the article's opening and the last from its ending, in the order the images are shown. Each image is drawn from its prompt with its scene added. One more AI call per run. | Off |
-
-Where the scene goes:
-
-- A prompt with `{{Scene}}` gets the scene there, for example a line `Scene: {{Scene}}` under the prompt's first sentence. `{{Scene}}` is never a field to fill in: Slopify writes it.
-- A prompt without it gets the scene as a line of its own after its first paragraph, so any prompt works unchanged.
-- With the switch off, a line holding `{{Scene}}` is left out and the prompt is drawn as it always was.
-- A **thumbnail** prompt with `{{Scene}}` gets a scene from a call of its own (one more AI call, in the Thumbnail stage, so changing the thumbnail never remakes the images): the article's most striking moment, the one that would make someone click, taken from anywhere in the article. With **Thumbnails** set to 3, each thumbnail gets a different moment, so the A/B test compares ideas as well as compositions. A thumbnail prompt without `{{Scene}}` is drawn as it always was.
-
-The style, composition and everything else in the prompt stay as written; only the scene changes from image to image. The scenes are written once the article exists, and each image waits for them. Switching it on or off in **Edit project** remakes the images.
-
-## Looks looked up: {{Appearance}}
-
-An image model draws a named figure from whatever it half remembers, so the same character can look different in every image. Put `{{Appearance}}` in an image, thumbnail, establishing or shorts image prompt, for example a line `Looks: {{Appearance}}`, and Slopify looks the looks up instead.
-
-- Once the article exists, one call to the project's AI model **searches the web** for how the video's subject and every named character in the article look: build, face, clothing, colours and the marks that make them recognisable. Where depictions disagree, it describes the most iconic one.
-- With **Scenes from the article** on, each picture gets the looks of the figures its scene names (up to three besides the subject), so a scene of a place or of someone else isn't redrawn with the subject in it; a scene that names no one leaves the looks line out. A thumbnail always gets the subject's look. Without scenes, every picture gets the subject's look.
-- There is no switch: a prompt with `{{Appearance}}` turns it on, and prompts without it are drawn as they always were. `{{Appearance}}` is never a field to fill in.
-- It costs one more AI call per run, with web search. The pictures that use it wait for it.
-
-## How long each image stays on screen
-
-**Seconds per image** (1 to 600, default 15) is in the **Video and style** row, beside **Cuts**, **Zoom** and **Motion**. When cuts follow the narration, it is the target length and a cut waits for a sentence end. When images run out, they start again. See [Play Video and Style](Play-Video-and-Style).
-
-## The thumbnail and the shorts
-
-The thumbnail and the shorts' images use the same image provider and model. If the video's images are not generated but the thumbnail is, the thumbnail gets its own **Provider**, **Model** and **Effort** pickers in the **Outputs** row. See [Play Outputs](Play-Outputs) and [Shorts](Shorts).
-
-## What the row summary says
-
-Folded, the Images row lists each ticked prompt with its Number, the provider and model, and "establishing image" when one is on, for example `Scene × 6, Portrait × 2 · fal.ai · flux-pro · establishing image`. With Provide it says how many of your images there are.
-
-## Tips
-
-- Keep one style across the video with an establishing image, instead of repeating the style in every image prompt.
-- Picture reviews can check each image for malformed hands, stray text and a match with its brief. They need Claude Code or Codex as the reviewer. See [Reviews and Checkpoints](Reviews-and-Checkpoints).
-- After the run, you can add, remove or regenerate single images on the project page. See [Editing a Project](Editing-a-Project).
-
-## Related pages
-
-- [Play Overview](Play-Overview)
-- [Prompts](Prompts)
-- [Cast Library](Cast-Library)
-- [Channels](Channels)
-- [Models](Models)
-- [Costs and Run Cost](Costs-and-Run-Cost)
-- [Play Video and Style](Play-Video-and-Style)
-- [Play Outputs](Play-Outputs)

package/dist/tutorials/Play-Narration.md

@@ -1,167 +0,0 @@
-# Play Narration
-
-The narration is the article read aloud by a text-to-speech (TTS) voice. On Play you pick the service, model and voice, and fine-tune how the text is prepared, split, paced and levelled. You get a narration track that the captions, cuts, chapters and shorts are all timed from.
-
-**Where to find it:** Play → **Narration** row → **Change**. The pauses, the volume levelling and the silences sit in Play → **Video and style**, and **Show tables and figures on screen** sits in Play → **Outputs**; they are described here because they shape the narration.
-
-## Choose where the narration comes from
-
-The Narration row starts with a **Source** switch:
-
-| Source | What happens | Cost |
-| --- | --- | --- |
-| **Generate** (default) | A TTS voice reads the article aloud. | Charged by the provider per character |
-| **Provide** | Uses an audio file you upload (**Narration file**), as it is. | None |
-| **Off** | Makes a silent video with no captions, YouTube description or shorts. The row reads "Off, a silent video". | None |
-
-With **Provide**, the file is used as is: "Uploaded narration is used as-is; include any intro and outro in that file." It is never levelled piece by piece; only the final master reaches it when **Level the volume** is on.
-
-## Pick a voice
-
-1. Open the **Narration** row and leave **Source** on **Generate**.
-2. Pick the **TTS** provider. A greyed provider says why it cannot be used; add its key under Settings.
-3. Pick the **TTS model**.
-4. Pick a **Voice**. If the list says "No voices. Add one in Settings.", add a voice first (see [Add a voice](#add-a-voice-under-settings--voices)).
-
-| Option | What it does | Default |
-| --- | --- | --- |
-| **TTS** | The text-to-speech service, charged per character of text: ElevenLabs, OpenAI, Cartesia, Inworld, Google Gemini, or **System voice**, your computer's own speech, which is free (greyed as **Speech Program Missing** when none is found; see [the system voice](Providers-and-Keys#the-system-voice)). Changing it clears the model and voice. | Your Settings default |
-| **TTS model** | The provider's speech model. Models differ in quality, languages, speed and price per character. Narration Preparation needs Inworld TTS-2. The refresh button asks the provider for its current list; **Custom ID** lets you type one. | Your Settings default |
-| **Voice** | Who reads the narration: the voices you added under Settings → Voices for this provider, filtered to the project's language. With several speakers, this voice reads the intro and outro. | None |
-| **Show all voices** | The voice list hides voices listed for other languages than the project's. Tick this to pick one anyway, for example a multilingual voice whose languages are listed wrong. The label says how many are hidden. A voice with unknown languages is always shown. | Off |
-
-### Several speakers
-
-Under the voice is a **Speakers** disclosure. It reads "Narration, one voice" by default. Open it to pick an audiobook, podcast, radio drama or interview format with several speakers, each with their own voice. See [Multiple Voices](Multiple-Voices) for every speaker setting, and [Other Languages](Other-Languages) for narrating in another language.
-
-## More audio settings
-
-**More audio settings** is a disclosure under the voice. Its line says what is not at the default, for example `words · intro Welcome · glossary on`.
-
-### Chunking
-
-How the narration is split into TTS requests. Split it when a provider refuses long text. It changes the number of requests, not the characters charged.
-
-| Option | What it does | Default |
-| --- | --- | --- |
-| **Chunking** | **Whole** sends the narration in one request. **Paragraph** sends one per paragraph. **Every N words** or **Every N characters** ends each request at a sentence end. | **Whole** |
-| **Words** / **Characters** (chunk size) | How long each request may be. Each request ends at the last whole sentence that fits, so a single longer sentence stays whole. Characters count spaces. | 500 words, or 3000 characters |
-
-Up to 10,000 words or 1,000,000 characters per chunk.
-
-### Intro and outro
-
-**Intro** and **Outro** pick Library entries read before and after the article. See [Play Title and Article](Play-Title-and-Article#intro-and-outro) and [Intros and Outros](Intros-and-Outros).
-
-### Narration Preparation
-
-Has the text model add delivery directions and sounds, such as a sigh or a laugh, following the Library narration prompt you pick. The article and captions stay unchanged.
-
-| Option | What it does | Default |
-| --- | --- | --- |
-| **Narration Preparation** | Pick a narration prompt from the Library, or **Off**. One text-model call per narration chunk and per intro or outro entry. | Off |
-
-It needs the Inworld TTS-2 model. With another model, the field says "Choose Inworld TTS-2 or turn preparation Off." With several speakers it works per speaker: each turn of a speaker on Inworld TTS-2 is prepared on its own, with the speaker's name and role, so every voice gets its own cues. At least one speaker must use TTS-2; turns of speakers on other voices are spoken as written. See [Multiple Voices](Multiple-Voices). Preparation is written by the text model: when nothing earlier needs one (a pasted article, say), **Text generation** appears in this row.
-
-### Pronunciation Glossary
-
-| Option | What it does | Default |
-| --- | --- | --- |
-| **Use Pronunciation Glossary** | Reads names with the IPA in the article's Pronunciation Glossary, such as `Arda: /ˈɑɹdə/`, with no extra text-model call. Works with Inworld TTS-2 and TTS-2 Flash. The written text stays unchanged. | On |
-| **Also use pronunciations from my other projects** | Adds every term from your other projects' glossaries, copied when this project starts. This project's own glossary wins where they differ. Turn it off to use only this article's glossary. | On |
-
-With another provider or model the switch is greyed and says "Unavailable for this provider or model. Your saved preference is retained."
-
-To get a glossary, ask for one in your article prompt: a section in slash-delimited standard-English IPA, one `Term: /IPA/` per line, with an English approximation for foreign names. A line with sounds English lacks is read as plain text. The glossary is never narrated itself. See [Narration Aliases and Glossary](Narration-Aliases-and-Glossary).
-
-### Narration aliases
-
-| Option | What it does | Default |
-| --- | --- | --- |
-| **Use narration aliases** | Says the words listed in Library → Narration aliases the way they are written there, such as `Dr.` as `Doctor`, with any generated voice. They are copied when the project starts. The article and captions keep the written words. | On |
-
-Manage the list in [Narration Aliases and Glossary](Narration-Aliases-and-Glossary).
-
-### Tables, figures and code
-
-An article written to be read can contain tables, pictures, equations and code. Read aloud cell by cell or symbol by symbol, they are noise.
-
-| Option | What it does | Default |
-| --- | --- | --- |
-| **Describe tables and figures in the narration** | The text model writes a short spoken passage for each table, picture, equation and code block (a table's pattern, what a figure or equation means, what code does), and the narration says it in its place. One extra text-model call per block, in the estimate and kept for reuse. The article and PDF keep the real table; captions show what is said. Needs a text model. | On |
-| **Leave code out** | Shown under the switch above. Drops code blocks from the narration instead of summarising each in a sentence or two. Tables, figures and equations are still described. | Off |
-| **Show tables and figures on screen** (in the **Outputs** row) | Each block the narration describes is also shown in the video while it is described: the article's own picture for a figure, a card drawn in your brand kit's title font and colour for the rest. The images take turns around them, and Shorts that include one show it upright. Drawn on this computer at no cost. Offered while the narration describes tables and figures. | On |
-
-Even with the switch off, some things are handled for you: links are read without their address, and footnote markers, the Sources Consulted section and the Pronunciation Glossary are never narrated.
-
-## Pauses between sentences and paragraphs
-
-Some voices run one sentence into the next with barely a breath. These settings add quiet where the voice's own pause is shorter. They never shorten a pause or cut a word, and the captions follow. They are in the **Video and style** row, beside **Level the volume**, and only show while the narration is generated.
-
-| Option | What it does | Default / range |
-| --- | --- | --- |
-| **Pause between sentences (seconds)** | The least quiet after each sentence. About 0.25 s is brisk, 0.35 to 0.45 natural or documentary, 0.5 to 0.8 an audiobook's relaxed pace, 0.8 and up sleep content. 0 keeps the voice's own. | 0.4; 0 to 2 in steps of 0.05 |
-| **Pause between paragraphs (seconds)** | The least quiet at the end of a paragraph, when you want more than between sentences. Try 0.8 to 1.2 for a slower read. 0 gives paragraphs the sentence pause. | 0; 0 to 2 in steps of 0.05 |
-
-The pauses are added on this computer before the word timing, so the captions, cuts, shorts and YouTube chapters stay in step. With several speakers, the gap between turns is **Gap between turns** under Speakers instead.
-
-## Level the volume
-
-TTS comes back at a different loudness for every voice and even every request, so a joined narration can jump between quiet and loud. **Level the volume** brings every narration piece (each chunk, each intro and outro, each speaker's turn) to one loudness before they are joined, then sets the finished video, shorts and audio files to a target loudness. It runs on this computer with no API calls. It is in the **Video and style** row and shows whenever there is narration.
-
-| Option | What it does | Default / range |
-| --- | --- | --- |
-| **Level the volume** | Turns levelling on or off for this run. A draft that never changed it follows Settings → General. | On |
-| **Video volume** | How loud the finished video and shorts are. 0 dB is −14 LUFS, what YouTube and Spotify play everything at. Peaks always stay under −1.5 dBTP. | 0 dB; −10 to +4 dB in steps of 0.5 |
-| **Audio files volume** | How loud the audio-only WAV and an audiobook's MP3 and M4B are. 0 dB is −18 LUFS, the level audiobook shops ask for. Peaks always stay under −3 dBTP. | 0 dB; −10 to +4 dB in steps of 0.5 |
-
-Type each volume in **dB** or as a **%** of the recommended level; the other box follows. −6 dB is about 50% and +4 dB about 158%. The help line under each field says the LUFS it stands for. LUFS is how loud a file sounds on average, measured the way ears hear it.
-
-## Silence at the edges and between segments
-
-Both are in the **Video and style** row and only show while there is narration.
-
-| Option | What it does | Default / range |
-| --- | --- | --- |
-| **Silence at start and end (seconds)** | Quiet time before the narration starts and after it ends. | 2; 0 to 30 |
-| **Silence between segments (seconds)** | Quiet between the intro and the narration, and between the narration and the outro. Only matters when an intro or outro is set. Leave it empty to use the gap set in Settings. | Settings value (3 unless changed); 0 to 30 |
-
-## Add a voice under Settings → Voices
-
-The **Voice** list on Play only offers voices you have added.
-
-1. Open Settings → **Voices**.
-2. Fill in **Voice name**, **Provider**, **Voice ID** and, optionally, **Languages**.
-3. Press **Add voice**. The voice joins the table above the form.
-4. Optional: tick **Real person** on the voice's row in the table if it imitates a real person.
-
-| Field | What it does |
-| --- | --- |
-| **Voice name** | The name you pick this voice by on Play and in Edit project. Only you see it. |
-| **Provider** | The TTS service the voice ID belongs to. Only providers set up under Settings are listed. |
-| **Voice ID** | The provider's own id for the voice, copied from its voice library. It is not checked now; a wrong id fails when a run's narration uses it. |
-| **Languages** | The languages the voice speaks, as codes such as `es`, `de`. Play lists the voice only for projects in these languages. Blank asks the provider when it can say; a voice with unknown languages is offered for every language. |
-| **Real person** | Turn on for a voice cloned from, or made to sound like, a real person. Prepare upload then answers Yes to YouTube's AI use question for videos it narrates. An AI voice that imitates no one stays off. |
-
-See [Settings Reference](Settings-Reference) and [Publishing to YouTube](Publishing-to-YouTube).
-
-## What the row summary says
-
-Folded, the Narration row shows the provider and voice (or the speakers format and count), and any preparation prompt, intro and outro, for example `Inworld · Ada · intro Welcome`. With Provide it shows your file's name.
-
-## Tips
-
-- If a provider refuses long requests, switch **Chunking** to **Paragraph** or **Every 500 words**. The characters charged stay the same.
-- Listen to the narration on the project page before publishing, in Slopify's own player (see [Project Page](Project-Page#the-players)). Fix a single chunk there instead of re-running everything. See [Editing a Project](Editing-a-Project).
-- An automatic review can check the narration for missing or garbled passages. See [Reviews and Checkpoints](Reviews-and-Checkpoints).
-
-## Related pages
-
-- [Play Overview](Play-Overview)
-- [Multiple Voices](Multiple-Voices)
-- [Other Languages](Other-Languages)
-- [Narration Aliases and Glossary](Narration-Aliases-and-Glossary)
-- [Intros and Outros](Intros-and-Outros)
-- [Prompts](Prompts)
-- [Providers and Keys](Providers-and-Keys)
-- [Play Video and Style](Play-Video-and-Style)