odori 0.0.1 → 0.0.2

package/LICENSE

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

package/README.md

@@ -1,3 +1,35 @@
 # odori
 
-Name reserved for an in-development code-first video framework.
+An independent React video framework. Odori owns the deterministic frame
+runtime, timeline compiler, browser player, and render manifest, plus the
+conventions a production video project otherwise has to invent.
+
+```bash
+npm install odori
+```
+
+```tsx
+import {Scene, Video, defineVideoMetadata} from "odori";
+
+export const metadata = defineVideoMetadata({
+  id: "launch",
+  title: "Product launch",
+  duration: "8s",
+});
+
+export default function LaunchVideo() {
+  return (
+    <Video>
+      <Scene id="opening" duration="5s">
+        <TitleReveal title="Video projects deserve a framework." />
+      </Scene>
+      <Scene id="end" duration="3s">
+        <EndCard title="Built with odori" />
+      </Scene>
+    </Video>
+  );
+}
+```
+
+The CLI and Studio live in `@odori/cli`, and the component registry in
+`@odori/registry`.

package/dist/brand-D71KbhAe.d.ts

@@ -0,0 +1,253 @@
+type Duration = number | `${number}s` | `${number}ms` | `${number}f` | string;
+/**
+ * Convert an authoring duration into whole frames.
+ *
+ * Numbers are seconds, matching the JSX authoring model where `duration={4}`
+ * reads as four seconds. Suffixed strings are explicit.
+ */
+declare const framesFromDuration: (duration: Duration, fps: number) => number;
+declare const secondsFromFrames: (frames: number, fps: number) => number;
+declare const formatTimecode: (frames: number, fps: number) => string;
+
+/**
+ * Deterministic synthesis. A cue is code that produces samples, so a sound
+ * diffs, reviews, and upgrades like every other piece of source, and preview
+ * and export can run the identical function.
+ *
+ * The rules are the frame runtime's rules: no wall clock, no unseeded
+ * randomness, one sample rate. Same score in, same bytes out, on any machine.
+ */
+/** Every cue renders at this rate, so a score never depends on the host. */
+declare const SAMPLE_RATE = 48000;
+type Signal = {
+    /** One array per channel. Mono is one; the mix upmixes when it needs to. */
+    channels: Float32Array[];
+    sampleRate: number;
+};
+type Envelope = {
+    /** Seconds from the start of the cue to full level. */
+    attack?: number;
+    /** Seconds from full level to the sustain level. */
+    decay?: number;
+    /** Level held after the decay, 0 to 1. */
+    sustain?: number;
+    /** Seconds to fall from the sustain level to silence. */
+    release?: number;
+};
+/**
+ * A seeded generator, so noise is reproducible. Mulberry32: small, fast, and
+ * good enough for audio noise, where the requirement is "no audible pattern"
+ * rather than cryptographic quality.
+ */
+declare const seeded: (seed: number) => (() => number);
+declare const silence: (samples: number, channels?: number) => Signal;
+/** A sine partial. The building block for tones, ticks, and sub weight. */
+declare const sine: (samples: number, frequency: number, phase?: number) => Signal;
+/** A triangle partial: softer than a square, brighter than a sine. */
+declare const triangle: (samples: number, frequency: number) => Signal;
+/** White noise from a seeded generator, so a click is the same click twice. */
+declare const noise: (samples: number, seed?: number) => Signal;
+/**
+ * A frequency sweep, which is what a riser is. Linear in frequency rather than
+ * in pitch, because the shape is easier to reason about when writing one.
+ */
+declare const sweep: (samples: number, from: number, to: number) => Signal;
+/** Apply an ADSR shape. Anything omitted is skipped rather than defaulted. */
+declare const shape: (signal: Signal, envelope: Envelope) => Signal;
+declare const gain: (signal: Signal, amount: number) => Signal;
+/** Sum signals, padding to the longest. Levels are the caller's business. */
+declare const mix: (...signals: Signal[]) => Signal;
+/**
+ * One pole filters. Enough to shape a click or take the top off a pad, and
+ * cheap enough to stay readable next to the sound it is making.
+ */
+declare const lowPass: (signal: Signal, frequency: number) => Signal;
+declare const highPass: (signal: Signal, frequency: number) => Signal;
+/**
+ * Join a signal's tail to its own head, so repeating it is inaudible.
+ *
+ * `declick` is wrong for a loop: ramping both edges to zero puts a hole at
+ * every seam, once per bar for the length of the video. Instead the tail is
+ * crossfaded over the head, which is the same trick a sampler uses — the last
+ * few milliseconds fade out while the copy of them under the first few
+ * milliseconds fades in, so the two ends already agree when they meet.
+ *
+ * The crossfade eats `milliseconds` from the end, which is why a looping score
+ * should be written a hair long rather than exactly one bar.
+ */
+declare const seamless: (signal: Signal, milliseconds?: number) => Signal;
+/** Peak normalize, so a cue lands predictably before the mix's loudness pass. */
+declare const normalize: (signal: Signal, peak?: number) => Signal;
+/** Repeat a signal until it fills `samples`, for beds under a long scene. */
+declare const loop: (signal: Signal, samples: number) => Signal;
+/** Seconds to samples at the fixed rate, so scores read in musical time. */
+declare const seconds: (value: number) => number;
+/**
+ * Scientific pitch to frequency: `a4` is 440 Hz, `c#3` and `db3` are the same
+ * key. A score names notes because "a2" survives transposition and reading,
+ * and 110 does neither.
+ */
+declare const note: (name: string) => number;
+/** Samples in one step of a grid, so a score can size its own voices. */
+declare const step: (bpm: number, division?: number) => number;
+type Step = {
+    /** Grid position, in steps from the start. Fractions are allowed. */
+    at: number;
+    /** The voice to place there, built at whatever length it needs. */
+    play: (samples: number) => Signal;
+    /** Length in steps. Defaults to one step. */
+    length?: number;
+    /** Linear gain for this hit. */
+    gain?: number;
+};
+/**
+ * Place voices on a tempo grid.
+ *
+ * A step's `play` receives the samples its length works out to, so one voice
+ * definition serves a sixteenth and a whole bar. Swing delays every odd step
+ * by a fraction of a step, which is the difference between a drum machine and
+ * a groove; it is off by default because a bed under narration should not
+ * shuffle unless it was asked to.
+ */
+declare const sequence: (steps: Step[], options: {
+    bpm: number;
+    division?: number;
+    swing?: number;
+    samples?: number;
+}) => Signal;
+/** Intervals from the root, in semitones. Enough colour for product scoring. */
+declare const QUALITIES: {
+    readonly major: readonly [0, 4, 7];
+    readonly minor: readonly [0, 3, 7];
+    readonly sus2: readonly [0, 2, 7];
+    readonly sus4: readonly [0, 5, 7];
+    readonly major7: readonly [0, 4, 7, 11];
+    readonly minor7: readonly [0, 3, 7, 10];
+    readonly add9: readonly [0, 4, 7, 14];
+};
+type ChordQuality = keyof typeof QUALITIES;
+/**
+ * The frequencies of a chord, root first. Voicing is left to the caller: what
+ * makes a pad sound like a pad is which of these you hand to which oscillator,
+ * and at what level.
+ */
+declare const chord: (root: string | number, quality?: ChordQuality) => number[];
+/**
+ * Sustained tones under one envelope: the sound of a bed that is holding
+ * rather than playing. Each voice is detuned by a few cents against the last
+ * so the stack beats slowly instead of standing still, which is what separates
+ * a pad from a test tone.
+ */
+declare const pad: (frequencies: number[], samples: number, options?: {
+    envelope?: Envelope;
+    detuneCents?: number;
+    level?: number;
+}) => Signal;
+
+type CueContext = {
+    /** How many samples the cue must fill. */
+    samples: number;
+    sampleRate: number;
+};
+type CueDefinition = {
+    readonly kind: "odori-cue";
+    /** The name a brand registers and a video asks for. */
+    name: string;
+    /** Length at 30fps, which is how a contract states it. */
+    durationInFrames: number;
+    /**
+     * Whether this score is one repeatable phrase rather than a single event.
+     *
+     * A looping cue renders its phrase once, at `durationInFrames`, and the
+     * placement repeats it for as long as the window runs: one render, cached by
+     * content, however long the scene. It also changes how the edges are
+     * treated — see `defineCue` — and makes `<Audio>` loop by default, so a bed
+     * fills its scene without the author restating what the cue already knows.
+     */
+    loops: boolean;
+    /**
+     * Anything the score reads. Held separately from the function so the
+     * manifest can hash what a cue depends on: two cues that differ only in a
+     * parameter are two different sounds and must not share a cached render.
+     */
+    params: Record<string, number | string | boolean>;
+    render(context: CueContext): Signal;
+};
+type CueInput = Omit<CueDefinition, "kind" | "loops" | "params"> & {
+    loops?: boolean;
+    params?: Record<string, number | string | boolean>;
+};
+/**
+ * A sound as source. The function runs unchanged in the browser for preview and
+ * in Node for export, so the cue a reviewer approves is the cue that ships.
+ */
+declare const defineCue: (input: CueInput) => CueDefinition;
+declare const isCueDefinition: (value: unknown) => value is CueDefinition;
+/**
+ * Identity of a rendered cue. The name alone is not enough, because a project
+ * can redefine what a name means; the params and the duration are what change
+ * the samples, so they are what the cache and the manifest key on.
+ */
+declare const cueSignature: (cue: CueDefinition) => string;
+/** The samples a cue occupies at the given frame rate. */
+declare const cueSamples: (cue: CueDefinition, fps: number) => number;
+/**
+ * A generated cue resolves to a URL that names its own content, so the render
+ * worker can serve it, the mix can find it on disk, and an unchanged cue is
+ * never rendered twice.
+ */
+declare const cueUrl: (cue: CueDefinition) => string;
+
+type BrandColors = {
+    background: string;
+    surface: string;
+    foreground: string;
+    muted: string;
+    accent: string;
+    border: string;
+};
+type BrandTypography = {
+    sans: string;
+    mono: string;
+    display?: string;
+};
+type BrandFont = {
+    family: string;
+    url: string;
+    weight?: string;
+    integrity?: string;
+};
+type Brand = {
+    readonly kind: "odori-brand";
+    name: string;
+    colors: BrandColors;
+    typography: BrandTypography;
+    fonts: BrandFont[];
+    logos: Record<string, string>;
+    motion: {
+        standard: [number, number, number, number];
+        staggerFrames: number;
+    };
+    audio: {
+        /**
+         * Symbolic cue names, so a video says what a sound means and the brand
+         * decides which file that is. Values are asset references or URLs.
+         */
+        cues: Record<string, string | CueDefinition>;
+        targetLufs: number;
+    };
+};
+type BrandInput = {
+    name?: string;
+    colors?: Partial<BrandColors>;
+    typography?: Partial<BrandTypography>;
+    fonts?: BrandFont[];
+    logos?: Record<string, string>;
+    motion?: Partial<Brand["motion"]>;
+    audio?: Partial<Brand["audio"]>;
+};
+declare const defaultBrand: Brand;
+declare const defineBrand: (input: BrandInput) => Brand;
+declare const brandCssVariables: (brand: Brand) => Record<string, string>;
+
+export { note as A, type Brand as B, type ChordQuality as C, type Duration as D, type Envelope as E, pad as F, seamless as G, seconds as H, secondsFromFrames as I, seeded as J, sequence as K, shape as L, silence as M, sine as N, step as O, sweep as P, triangle as Q, type Signal as S, type BrandColors as a, type BrandFont as b, type BrandInput as c, type BrandTypography as d, type CueContext as e, type CueDefinition as f, SAMPLE_RATE as g, type Step as h, brandCssVariables as i, chord as j, cueSamples as k, cueSignature as l, cueUrl as m, defaultBrand as n, defineBrand as o, defineCue as p, formatTimecode as q, framesFromDuration as r, gain as s, highPass as t, isCueDefinition as u, loop as v, lowPass as w, mix as x, noise as y, normalize as z };