@hypit/caption-fine 0.0.0-stage → 0.1.1

package/dist/schedule.d.ts

@@ -0,0 +1,12 @@
+import type { CaptionProgram, CaptionTiming } from "@hypit/hypit/caption";
+import type { CaptionDocument } from "@hypit/hypit/caption";
+import type { FineCaptionSchedule } from "./types.js";
+/**
+ * Resolve visible Cue envelopes before the renderer runs.
+ *
+ * Resolved unit timing stays untouched. `leadFrames` and `tailFrames` only
+ * widen the visible envelope, and `cut` prevents adjacent Cues from competing
+ * for the same handoff interval without shortening either Cue's spoken time.
+ */
+export declare function scheduleFineCaption(timing: CaptionTiming, program: CaptionProgram, document: CaptionDocument): FineCaptionSchedule;
+export declare function assertFineCaptionSchedule(value: FineCaptionSchedule): void;

package/dist/schedule.js

@@ -0,0 +1,135 @@
+import { assertCaptionProgramForDocument, assertCaptionTimingForDocument, captionUseVisibility } from "@hypit/hypit/caption";
+import { assertFineCaptionParameters, FINE_CAPTION_FAMILY } from "./style.js";
+function assertIntegerFrame(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`${label} must be a non-negative integer Frame`);
+}
+/** Join authored Cues to their complete absolute Unit timing. */
+function fineCaptionContentCues(timing, document) {
+    const timingByUnit = new Map(timing.units.map((unit) => [unit.unitId, unit]));
+    return document.cues.map((cue) => {
+        const units = cue.unitIds.map((unitId) => timingByUnit.get(unitId));
+        return {
+            id: cue.id,
+            ...(cue.role === undefined ? {} : { role: cue.role }),
+            startFrame: Math.min(...units.map((unit) => unit.startFrame)),
+            endFrameExclusive: Math.max(...units.map((unit) => unit.endFrameExclusive)),
+            units,
+        };
+    });
+}
+/**
+ * Resolve visible Cue envelopes before the renderer runs.
+ *
+ * Resolved unit timing stays untouched. `leadFrames` and `tailFrames` only
+ * widen the visible envelope, and `cut` prevents adjacent Cues from competing
+ * for the same handoff interval without shortening either Cue's spoken time.
+ */
+export function scheduleFineCaption(timing, program, document) {
+    assertCaptionProgramForDocument(program, document);
+    assertCaptionTimingForDocument(timing, document);
+    const parameters = new Map();
+    const activeStyles = new Set(program.uses.map(use => use.styleId));
+    for (const style of program.styles) {
+        if (!activeStyles.has(style.id))
+            continue;
+        if (style.rendering === null)
+            continue;
+        if (style.rendering.family !== FINE_CAPTION_FAMILY) {
+            throw new Error(`Fine Caption cannot schedule Style family ${style.rendering.family}`);
+        }
+        const value = style.rendering.parameters;
+        assertFineCaptionParameters(value);
+        parameters.set(style.id, value);
+    }
+    const contentCues = fineCaptionContentCues(timing, document);
+    const roleByCue = new Map(contentCues.map((cue) => [cue.id, cue.role]));
+    const cues = [];
+    for (const [index, use] of program.uses.entries()) {
+        if (use.window !== undefined && use.window.start.timelineId !== timing.timelineId)
+            throw new Error("Caption Use belongs to another Timeline");
+        const style = parameters.get(use.styleId);
+        if (style === undefined)
+            continue; // Hidden still participates in coverage below.
+        const desired = contentCues.filter(cue => use.role === undefined || cue.role === use.role).map((cue) => ({
+            id: `${use.id}:${cue.id}`, cueId: cue.id, styleId: use.styleId,
+            timedStartFrame: cue.startFrame, timedEndFrameExclusive: cue.endFrameExclusive,
+            visibleStartFrame: Math.max(0, cue.startFrame - style.timing.leadFrames),
+            visibleEndFrameExclusive: cue.endFrameExclusive + style.timing.tailFrames,
+            units: cue.units, visibility: [],
+        }));
+        // Resolve each speaker's ordinary Cue handoff before masking by Use windows.
+        desired.sort((a, b) => a.timedStartFrame - b.timedStartFrame);
+        const previousByRole = new Map();
+        const envelopes = [];
+        for (const wanted of desired) {
+            let cue = wanted;
+            const role = roleByCue.get(cue.cueId);
+            const previousIndex = previousByRole.get(role);
+            const previous = previousIndex === undefined ? undefined : envelopes[previousIndex];
+            if (previous !== undefined && style.timing.handoff === "cut" && previous.timedEndFrameExclusive <= cue.timedStartFrame) {
+                const previousEnd = Math.max(previous.timedEndFrameExclusive, Math.min(previous.visibleEndFrameExclusive, cue.timedStartFrame));
+                envelopes[previousIndex] = { ...previous, visibleEndFrameExclusive: previousEnd };
+                cue = { ...cue, visibleStartFrame: Math.min(cue.timedStartFrame, Math.max(cue.visibleStartFrame, previousEnd)) };
+            }
+            previousByRole.set(role, envelopes.length);
+            envelopes.push(cue);
+        }
+        for (const cue of envelopes) {
+            const role = roleByCue.get(cue.cueId);
+            const visibility = captionUseVisibility(program, index, role, { startFrame: cue.visibleStartFrame, endFrameExclusive: cue.visibleEndFrameExclusive });
+            if (visibility.length)
+                cues.push({ ...cue, visibility });
+        }
+    }
+    const ids = new Set();
+    for (const cue of cues) {
+        if (ids.has(cue.id))
+            throw new Error(`Fine Caption Schedule repeats Cue ${cue.id}`);
+        ids.add(cue.id);
+        assertIntegerFrame(cue.timedStartFrame, `Fine Caption Cue ${cue.id} timed start`);
+        assertIntegerFrame(cue.timedEndFrameExclusive, `Fine Caption Cue ${cue.id} timed end`);
+        assertIntegerFrame(cue.visibleStartFrame, `Fine Caption Cue ${cue.id} visible start`);
+        assertIntegerFrame(cue.visibleEndFrameExclusive, `Fine Caption Cue ${cue.id} visible end`);
+        if (cue.timedEndFrameExclusive <= cue.timedStartFrame
+            || cue.visibleStartFrame > cue.timedStartFrame
+            || cue.visibleEndFrameExclusive < cue.timedEndFrameExclusive
+            || cue.visibleEndFrameExclusive <= cue.visibleStartFrame) {
+            throw new Error(`Fine Caption Cue ${cue.id} has an invalid visible envelope`);
+        }
+    }
+    return {
+        timelineId: timing.timelineId,
+        documentId: document.id,
+        cues,
+    };
+}
+export function assertFineCaptionSchedule(value) {
+    if (!value.timelineId || !value.documentId) {
+        throw new Error("Fine Caption Schedule provenance is empty");
+    }
+    const ids = new Set();
+    for (const cue of value.cues) {
+        if (!cue.id || !cue.styleId || ids.has(cue.id) || cue.units.length === 0) {
+            throw new Error("Fine Caption Schedule contains an invalid Cue");
+        }
+        ids.add(cue.id);
+        if (!cue.cueId || cue.visibility.length === 0 || cue.visibility.some(span => !Number.isSafeInteger(span.startFrame) || !Number.isSafeInteger(span.endFrameExclusive)
+            || span.startFrame < cue.visibleStartFrame || span.endFrameExclusive > cue.visibleEndFrameExclusive
+            || span.endFrameExclusive <= span.startFrame))
+            throw new Error("Fine Caption visibility is invalid");
+        for (const [label, frame] of [
+            ["timed start", cue.timedStartFrame],
+            ["timed end", cue.timedEndFrameExclusive],
+            ["visible start", cue.visibleStartFrame],
+            ["visible end", cue.visibleEndFrameExclusive],
+        ])
+            assertIntegerFrame(frame, `Fine Caption Cue ${cue.id} ${label}`);
+        if (cue.timedEndFrameExclusive <= cue.timedStartFrame
+            || cue.visibleStartFrame > cue.timedStartFrame
+            || cue.visibleEndFrameExclusive < cue.timedEndFrameExclusive
+            || cue.visibleEndFrameExclusive <= cue.visibleStartFrame) {
+            throw new Error(`Fine Caption Cue ${cue.id} has an invalid visible envelope`);
+        }
+    }
+}

package/dist/spacing.d.ts

@@ -0,0 +1,7 @@
+import type { CaptionDisplayWord } from "@hypit/hypit/caption";
+type Surface = Pick<CaptionDisplayWord, "text" | "separatorBefore">;
+/** The first displayed word starts a line; all other gaps come from authored content. */
+export declare function wordGaps(words: readonly Surface[]): readonly boolean[];
+/** A uniform run can use column-gap; a mixed run requires individual separators. */
+export declare function uniformGap(gaps: readonly boolean[]): boolean | undefined;
+export {};

package/dist/spacing.js

@@ -0,0 +1,13 @@
+/** The first displayed word starts a line; all other gaps come from authored content. */
+export function wordGaps(words) {
+    return words.map((word, index) => index > 0 && word.separatorBefore === " ");
+}
+/** A uniform run can use column-gap; a mixed run requires individual separators. */
+export function uniformGap(gaps) {
+    const boundaries = gaps.slice(1);
+    if (boundaries.length === 0)
+        return false;
+    if (boundaries.every(gap => gap))
+        return true;
+    return boundaries.some(gap => gap) ? undefined : false;
+}

package/dist/studio.d.ts

@@ -0,0 +1,7 @@
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioItemDraft, StudioInspectorObjectDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-companion";
+export declare const captionFineInspectorFields: readonly StudioInspectorFieldDeclaration[];
+export declare function projectCaptionContents(context: StudioTrackCompanionContext): readonly StudioItemDraft[];
+export declare function projectCaption(context: StudioTrackCompanionContext): readonly StudioItemDraft[];
+export declare function projectCaptionUses(context: StudioTrackCompanionContext): readonly StudioInspectorObjectDraft[];
+export declare const captionFineStudioTrackCompanions: readonly StudioTrackCompanion[];
+export declare const captionFineStudioParameterCompanions: readonly import("@hypit/studio-companion").StudioParameterCompanion[];

package/dist/studio.js

@@ -0,0 +1,175 @@
+import { captionTypes } from "@hypit/hypit/caption";
+import { compositionTypes } from "@hypit/hypit/composition";
+import { fineCaptionEditableDefaults } from "./recipe.js";
+import { captionFineMarkupSurfaces, captionFineModuleRef } from "./manifest.js";
+import { authoredChildFor, requiredReferencedValue, requiredSurfaceValue } from "@hypit/studio-companion";
+const styleSurface = captionFineMarkupSurfaces.find((surface) => surface.name === "style");
+const recipeVocabulary = styleSurface?.vocabulary.attributes
+    .find((attribute) => attribute.name === "recipe")?.recipe ?? [];
+function title(name) {
+    return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+function valuesFor(property) {
+    return "values" in property ? property.values : undefined;
+}
+function captionPlace(domain, page, section) {
+    return {
+        domain,
+        page: { id: page, label: title(page) },
+        section: { id: section, label: title(section) },
+    };
+}
+const captionPlacement = new Map();
+function placeCaption(names, domain, page, section) {
+    for (const name of names)
+        captionPlacement.set(name, captionPlace(domain, page, section));
+}
+placeCaption(["stack-order", "x", "y", "width", "height", "anchor-x", "anchor-y"], "where", "placement", "region");
+placeCaption([
+    "align", "block-align", "inline-size", "wrap", "max-lines", "max-words-per-line", "direction",
+    "line-height", "letter-spacing", "word-gap",
+], "where", "flow", "flow");
+placeCaption(["size", "kerning", "caps", "text-transform"], "how", "text", "typography");
+placeCaption([
+    "fill", "opacity", "gradient-from", "gradient-to", "gradient-angle", "stroke-color", "stroke-width", "shadow-color",
+    "shadow-opacity", "shadow-x", "shadow-y", "shadow-blur", "shadow-spread", "long-shadow-color", "long-shadow-opacity",
+    "long-shadow-distance", "long-shadow-angle", "glow-color", "glow-opacity", "glow-blur", "glow-spread",
+], "how", "paint", "base-paint");
+placeCaption([
+    "active-fill", "active-opacity", "active-gradient-from", "active-gradient-to", "active-gradient-angle",
+    "active-stroke-color", "active-stroke-width", "active-shadow-color", "active-shadow-opacity", "active-shadow-x",
+    "active-shadow-y", "active-shadow-blur", "active-shadow-spread", "active-long-shadow-color",
+    "active-long-shadow-opacity", "active-long-shadow-distance", "active-long-shadow-angle", "active-glow-color",
+    "active-glow-opacity", "active-glow-blur", "active-glow-spread",
+], "how", "paint", "active-paint");
+placeCaption([
+    "background", "border-color", "border-width", "padding", "radius", "cue-shadow-color", "cue-shadow-opacity",
+    "cue-shadow-x", "cue-shadow-y", "cue-shadow-blur", "cue-shadow-spread",
+], "how", "cue-box", "cue-box");
+placeCaption([
+    "underline", "underline-color", "underline-thickness", "underline-offset", "active-underline-color",
+    "active-underline-thickness", "active-underline-offset", "active-box-background", "active-box-border-color",
+    "active-box-border-width", "active-box-padding", "active-box-radius",
+], "how", "decoration", "decoration");
+placeCaption(["lead-frames", "tail-frames", "handoff"], "when", "cue", "envelope");
+placeCaption([
+    "cue-enter", "cue-enter-frames", "cue-enter-start-scale", "cue-exit", "cue-exit-frames",
+], "when", "cue", "cue");
+placeCaption([
+    "karaoke", "karaoke-transition", "active-underline", "active-box", "active-box-continuity", "active-box-enter",
+    "active-box-exit", "active-box-transition-frames", "atom-enter", "atom-enter-frames", "atom-exit", "atom-exit-frames",
+    "atom-reveal", "active-response", "active-response-frames", "active-scale", "slide-distance",
+], "when", "token", "token");
+placeCaption(["loop", "loop-target", "loop-period-frames", "loop-intensity"], "when", "loop", "loop");
+const captionColorProperties = new Set([
+    "fill", "gradient-from", "gradient-to", "stroke-color", "shadow-color", "long-shadow-color", "glow-color",
+    "active-fill", "active-gradient-from", "active-gradient-to", "active-stroke-color", "active-shadow-color",
+    "active-long-shadow-color", "active-glow-color", "background", "border-color", "cue-shadow-color", "underline-color",
+    "active-underline-color", "active-box-background", "active-box-border-color",
+]);
+const captionTextProperties = new Set(["loop"]);
+const captionPercentProperties = new Set(["x", "y", "width", "height", "opacity", "active-opacity", "active-scale"]);
+const captionPixelProperties = new Set(["size", "letter-spacing", "word-gap", "radius", "stroke-width", "border-width", "shadow-blur", "glow-blur"]);
+export const captionFineInspectorFields = recipeVocabulary.map((property) => {
+    const placement = captionPlacement.get(property.name);
+    if (placement === undefined)
+        throw new Error(`Caption Studio has no explicit Inspector declaration for ${property.name}.`);
+    const options = valuesFor(property);
+    return {
+        binding: `style.${property.name}`,
+        label: title(property.name),
+        ...placement,
+        summary: property.summary,
+        control: options !== undefined ? "select" : captionColorProperties.has(property.name) ? "color"
+            : captionTextProperties.has(property.name) ? "text" : "number",
+        ...(options === undefined ? {} : { options }),
+        ...(captionPercentProperties.has(property.name) ? { unit: "%", number: { scale: 100, step: 1 } } : {}),
+        ...(captionPixelProperties.has(property.name) ? { unit: "px", number: { step: 1 } } : {}),
+    };
+});
+function cueText(document, unitIds) {
+    if (document === undefined)
+        return "";
+    const selected = new Set(unitIds);
+    return document.words
+        .filter((word) => selected.has(word.unitId))
+        .map((word, index) => (index === 0 ? "" : word.separatorBefore) + word.text)
+        .join("");
+}
+export function projectCaptionContents(context) {
+    const timing = requiredReferencedValue(context, "timing", captionTypes.timing);
+    const schedule = requiredSurfaceValue(context, "schedule");
+    const document = requiredReferencedValue(context, "document", captionTypes.document);
+    if (document.id !== timing.documentId)
+        throw new Error("Caption timing belongs to another CaptionDocument.");
+    const units = new Map(timing.units.map((unit) => [unit.unitId, unit]));
+    return document.cues.map((cue, index) => {
+        const timed = cue.unitIds.map((unitId) => {
+            const unit = units.get(unitId);
+            if (unit === undefined)
+                throw new Error(`Caption Cue ${cue.id} has no timing for Unit ${unitId}.`);
+            return unit;
+        });
+        if (timed.length === 0)
+            throw new Error(`Caption Cue ${cue.id} contains no Units.`);
+        const startFrame = Math.min(...timed.map((unit) => unit.startFrame));
+        const endFrameExclusive = Math.max(...timed.map((unit) => unit.endFrameExclusive));
+        return {
+            id: `${context.track.outputRef}:cue:${cue.id}`, authoredId: cue.id,
+            display: { title: `#${index + 1}`, layers: [{ kind: "text", role: "content", text: cueText(document, cue.unitIds) }] },
+            startFrame, endFrameExclusive, stackOrder: 0,
+            renderIds: schedule.cues.filter(item => item.cueId === cue.id).map(item => item.id),
+            presentation: { kind: "caption-cue", chrome: "standard" },
+            inspector: [
+                { id: "range", label: "Range", domain: "when", section: { id: "cue", label: "Cue" }, value: `${startFrame}–${endFrameExclusive}`, unit: "f" },
+                ...(cue.role === undefined ? [] : [{ id: "role", label: "Role", domain: "how", section: { id: "cue", label: "Cue" }, value: cue.role }]),
+            ],
+        };
+    });
+}
+export function projectCaption(context) {
+    return projectCaptionContents(context);
+}
+export function projectCaptionUses(context) {
+    const program = requiredSurfaceValue(context, "program");
+    return program.uses.map((use, index) => {
+        const child = authoredChildFor(context, use.id, []);
+        return {
+            id: `use:${use.id}`,
+            authoredId: use.id,
+            title: use.styleId,
+            ...(child === undefined ? {} : { elementRange: child.range }),
+            parameterReferences: { style: use.styleId },
+            inspector: [
+                { id: "order", label: "Order", domain: "how", section: { id: "rule", label: "Rule" }, value: index + 1 },
+                { id: "scope", label: "Scope", domain: "when", section: { id: "rule", label: "Rule" },
+                    value: use.window === undefined ? "All matching cues" : use.window.subjectId },
+                { id: "role", label: "Role", domain: "how", section: { id: "rule", label: "Rule" }, value: use.role ?? "Any" },
+            ],
+        };
+    });
+}
+export const captionFineStudioTrackCompanions = [
+    {
+        id: "track", role: "track",
+        output: { type: compositionTypes.visualTrack, surface: "caption", modules: [captionFineModuleRef] },
+        family: "caption", tone: "magenta", icon: "captions",
+        lane: { heightPx: 36 },
+        inspectorObjects: [{
+                id: "uses", label: "Presentation Rules",
+                bindings: [{ name: "style", companion: true }],
+                inspector: [{ binding: "style", label: "Style", domain: "how", section: { id: "style", label: "Style" }, control: "text" }],
+                project: projectCaptionUses,
+            }],
+        requiredValues: ["schedule", "program"], project: projectCaption,
+    },
+];
+export const captionFineStudioParameterCompanions = [{
+        id: "style", match: { module: captionFineModuleRef, surface: "style" },
+        bindings: [{ name: "font", companion: true }, { name: "recipe", recipe: { bindings: recipeVocabulary.map(({ name }) => ({ name,
+                        ...(Object.hasOwn(fineCaptionEditableDefaults, name) ? { fallback: fineCaptionEditableDefaults[name] } : {}),
+                    })) } }],
+        inspector: [
+            ...captionFineInspectorFields.map(field => ({ ...field, binding: field.binding.replace(/^style\./u, "recipe.") })),
+        ],
+    }];

package/dist/style.d.ts

@@ -0,0 +1,8 @@
+import type { CaptionStyleIntent } from "@hypit/hypit/caption";
+import type { FontArtifactRef } from "@hypit/hypit/media";
+import type { Recipe } from "@hypit/hypit/recipe";
+import type { FineCaptionParameters } from "./types.js";
+export declare const FINE_CAPTION_FAMILY = "@hypit/caption-fine@1";
+export declare function fineCaptionParameters(recipe: Recipe, exactFonts: readonly FontArtifactRef[]): FineCaptionParameters;
+export declare function assertFineCaptionParameters(value: FineCaptionParameters): void;
+export declare function fineCaptionStyle(id: string, recipe: Recipe, exactFonts: readonly FontArtifactRef[]): CaptionStyleIntent;