@vanillaskyai/video 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.4.0
+
+- Adds `loop` to `VideoPlayer` for saved videos. A completed video previously
+  painted its replay affordance and stopped, so there was no way to run one
+  continuously; with `loop` it restarts from the beginning and keeps its
+  soundtrack in step. Streaming playback is unchanged.
+- Adds `onSceneChange(scene, index)` to `VideoPlayer`, fired when the scene
+  under the playhead changes and again on index `0` each time a loop wraps.
+  Nothing previously reported playback position to the host: `onComplete`
+  reports the end of a stream, so it never fires for a saved video, and any UI
+  that had to stay in step ran a parallel timer that drifted silently.
+- Exports `resolveVideoBrand` from the root entry. `parseVideo` requires a
+  fully resolved brand, and the resolver already existed internally, so
+  hand-authoring a `Video` meant copying a defaults blob into application code.
+- Documents live channels — continuously playing, self-refreshing video built
+  from your own data rather than generated per viewer — in
+  `docs/live-channels.md`, with an example compiled against the packed package.
+
+## 0.3.4
+
+- Mounts a scene that brings a new photo or video 1.2s before it appears,
+  instead of 0.3s, so the element has time to decode and the scene arrives
+  showing its picture rather than a gradient that pops a beat later. The extra
+  time is invisible: the layer stays fully transparent until the existing
+  0.3s cross-fade begins, so every rendered frame is unchanged, and the mounted
+  element is handed to the incoming scene rather than rebuilt. Scenes that
+  reuse the backdrop already on screen are unaffected.
+
 ## 0.3.3
 
 - Keeps a soundtrack audible on iPhone Safari when its audio context cannot be

package/PUBLIC-API.md

@@ -63,6 +63,7 @@ a request, renders React, imports a provider, or accesses browser globals.
 
 - `getVideoDuration(video: Video): number`
 - `parseVideo(value: unknown): Video`
+- `resolveVideoBrand(input?: VideoBrandInput): VideoBrand`
 - `VideoValidationError`
 
 ### Types
@@ -190,6 +191,17 @@ wants the completed video to begin with the first generated scene.
 Saved-video playback performs no generation request. `VideoPlayerBinding` and
 the internal reducer state are not public types.
 
+`loop` and `onSceneChange` apply to saved-video playback. `loop` restarts a
+completed video from the beginning instead of showing the replay affordance;
+`onSceneChange(scene, index)` fires whenever the scene under the playhead
+changes, including when a loop wraps back to the first scene. Streaming
+playback is unaffected by either.
+
+`resolveVideoBrand` fills a partial brand with the documented defaults and
+preset backgrounds, producing the fully resolved `VideoBrand` that `parseVideo`
+requires. Use it when authoring a `Video` by hand rather than copying default
+values into application code.
+
 ## Template authoring
 
 The template entry point owns React render definitions only. React-free server

package/README.md

@@ -1,6 +1,6 @@
 # Give your AI a video output
 
-![Version 0.3.3 beta](https://img.shields.io/badge/version-0.3.3_beta-7c3aed)
+![Version 0.4.0 beta](https://img.shields.io/badge/version-0.4.0_beta-7c3aed)
 
 **VanillaSky is the open-source video response layer.** Turn text, structured
 data, and live application context into personalized video responses that start
@@ -17,7 +17,7 @@ the planning prompt, trusted templates, validation, streaming, and player.
 For humans:
 
 ```bash
-npm install @vanillaskyai/video@0.3.3 ai @ai-sdk/openai
+npm install @vanillaskyai/video@0.4.0 ai @ai-sdk/openai
 ```
 
 For coding agents:
@@ -106,7 +106,7 @@ shows each complete, validated scene as soon as it is ready and returns a
 deterministic `Video` object when generation finishes.
 
 A copy-and-run app is in
-[`examples/nextjs-quickstart`](https://github.com/VanillaSkyAi/video/tree/v0.3.3/examples/nextjs-quickstart).
+[`examples/nextjs-quickstart`](https://github.com/VanillaSkyAi/video/tree/v0.4.0/examples/nextjs-quickstart).
 
 ## Shape the response
 
@@ -152,6 +152,7 @@ compiler: `npm install --save-dev tsx`.
 | Add brand or viewer context | [Branding and personalization](docs/branding-and-personalization.md) |
 | Add media or soundtrack audio | [Media and soundtrack audio](docs/media-and-audio.md) |
 | Persist and replay results | [Persistence and replay](docs/persistence.md) |
+| Run a looping, self-refreshing channel | [Live channels](docs/live-channels.md) |
 | Create source-owned templates | [Custom templates](docs/custom-templates.md) |
 | Test routes and streams | [Test integrations](docs/testing.md) |
 | Deploy securely | [Production](docs/production.md) · [Security](docs/security.md) |

package/dist/check-runtime.js

@@ -1,6 +1,6 @@
 import {
   VideoFrame
-} from "./chunk-HXSV6RHF.js";
+} from "./chunk-N3KUA7VP.js";
 import "./chunk-XWWLKRNU.js";
 import "./chunk-SPVTJH3F.js";
 import {

package/dist/{chunk-HXSV6RHF.js → chunk-N3KUA7VP.js}

@@ -31,6 +31,7 @@ function scaleSafeZone(zone, factor) {
 // src/player/video-frame.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
 var SCENE_TRANSITION_SECONDS = 0.3;
+var MEDIA_PREROLL_SECONDS = 1.2;
 var CONTIGUITY_ULP_FACTOR = 4;
 function clamp01(value) {
   return Math.max(0, Math.min(1, value));
@@ -51,6 +52,9 @@ function brandBackgroundFallback(config) {
   const background = config.style.brand.background;
   return background.type === "solid" ? background.color : background.colors[0];
 }
+function sceneHasBackdrop(range) {
+  return String(range.scene.variables.mediaType || "auto") !== "gradient" && String(range.scene.variables.mediaUrl || "").trim() !== "";
+}
 function sceneBackgroundChanges(left, right) {
   const mediaUrl = (range) => String(range.scene.variables.mediaType || "auto") === "gradient" ? "" : String(range.scene.variables.mediaUrl || "");
   return mediaUrl(left) !== mediaUrl(right);
@@ -178,6 +182,14 @@ function VideoFrame({
   );
   const blendStart = active.end - blendDuration;
   const blendEnd = blendStart + blendDuration;
+  const prerollsNext = Boolean(
+    contiguousNext && sceneHasBackdrop(contiguousNext) && sceneBackgroundChanges(active, contiguousNext)
+  );
+  const prerollDuration = prerollsNext ? Math.min(Math.max(MEDIA_PREROLL_SECONDS, blendDuration), Math.max(0, duration)) : blendDuration;
+  const prerollStart = active.end - prerollDuration;
+  const mountingNext = Boolean(
+    contiguousNext && time >= prerollStart && time < blendEnd && (eligibleNextTransition || prerollsNext)
+  );
   const previewingNext = Boolean(
     eligibleNextTransition && time >= blendStart && time < blendEnd
   );
@@ -232,7 +244,7 @@ function VideoFrame({
                 }
               }
             ),
-            previewingNext && contiguousNext && nextTiming ? [
+            mountingNext && contiguousNext ? [
               /* @__PURE__ */ jsx(
                 SceneLayer,
                 {
@@ -244,7 +256,7 @@ function VideoFrame({
                   width: canvas.width,
                   height: canvas.height,
                   playing,
-                  layer: "outgoing",
+                  layer: previewingNext ? "outgoing" : "active",
                   opacity: 1 - blendProgress,
                   interactive: true,
                   zIndex: 1

package/dist/{events-tQ0x-VaL.d.ts → events-D_1F6gw5.d.ts}

@@ -1,4 +1,4 @@
-import { f as VideoOrientation, h as VideoStyle, V as Video, k as VideoCapabilities, a as VideoAudio, g as VideoScene, l as VIDEO_PROTOCOL_VERSION } from './types-CVMb6QEq.js';
+import { b as VideoOrientation, V as VideoStyle, c as Video, a as VideoCapabilities, d as VideoAudio, e as VideoScene, f as VIDEO_PROTOCOL_VERSION } from './types-Cg0Onj7l.js';
 
 type VideoWarningCategory = "validation" | "readability" | "grounding" | "provider" | "media" | "protocol";
 type VideoWarningCode = "scene_duration_adjusted" | "scene_omitted_unreadable" | "scene_omitted_for_closer" | "scene_patch_rejected_readability" | "chart_scale_imbalance" | "plan_incomplete" | "plan_missing_closer" | "provider_warning" | "provider_diagnostics_unavailable";

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { V as Video } from './types-CVMb6QEq.js';
-export { a as VideoAudio, b as VideoBackground, c as VideoBrand, d as VideoInput, e as VideoKnowledgeMode, f as VideoOrientation, g as VideoScene, h as VideoStyle, i as VideoStyleOptions, j as VideoSuppliedMedia } from './types-CVMb6QEq.js';
+import { c as Video, g as VideoBrandInput, h as VideoBrand } from './types-Cg0Onj7l.js';
+export { d as VideoAudio, i as VideoBackground, j as VideoInput, k as VideoKnowledgeMode, b as VideoOrientation, e as VideoScene, V as VideoStyle, l as VideoStyleOptions, m as VideoSuppliedMedia } from './types-Cg0Onj7l.js';
 export { V as VideoStatus } from './state-DZcKuS32.js';
 
 type VideoValidationErrorCode = "invalid_video" | "unsupported_video_version";
@@ -12,4 +12,6 @@ declare function parseVideo(value: unknown): Video;
 
 declare function getVideoDuration(config: Video): number;
 
-export { Video, VideoValidationError, type VideoValidationErrorCode, getVideoDuration, parseVideo };
+declare function resolveVideoBrand(input?: VideoBrandInput): VideoBrand;
+
+export { Video, VideoBrand, VideoBrandInput, VideoValidationError, type VideoValidationErrorCode, getVideoDuration, parseVideo, resolveVideoBrand };

package/dist/index.js

@@ -6,9 +6,12 @@ import "./chunk-EE6PK6XC.js";
 import {
   getVideoDuration
 } from "./chunk-SPVTJH3F.js";
-import "./chunk-XGRA2MUV.js";
+import {
+  resolveVideoBrand
+} from "./chunk-XGRA2MUV.js";
 export {
   VideoValidationError,
   getVideoDuration,
-  parseVideo
+  parseVideo,
+  resolveVideoBrand
 };

package/dist/{kit-DlUSg8lA.d.ts → kit-DLeCr3d0.d.ts}

@@ -1,4 +1,4 @@
-import { h as VideoStyle, k as VideoCapabilities } from './types-CVMb6QEq.js';
+import { V as VideoStyle, a as VideoCapabilities } from './types-Cg0Onj7l.js';
 import { ComponentType } from 'react';
 import { S as SceneTemplateMetadata, d as TemplateJsonSchema, f as TemplateJsonSchemaProperty } from './catalog-types-BIhSpOWK.js';
 

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import { CSSProperties, ReactElement } from 'react';
-import { V as VideoEvent, a as VideoWarning } from './events-tQ0x-VaL.js';
-import { f as VideoOrientation, V as Video, d as VideoInput } from './types-CVMb6QEq.js';
-import { T as TemplateRegistry } from './kit-DlUSg8lA.js';
+import { V as VideoEvent, a as VideoWarning } from './events-D_1F6gw5.js';
+import { b as VideoOrientation, c as Video, e as VideoScene, j as VideoInput } from './types-Cg0Onj7l.js';
+import { T as TemplateRegistry } from './kit-DLeCr3d0.js';
 import { V as VideoStatus } from './state-DZcKuS32.js';
 import './catalog-types-BIhSpOWK.js';
 
@@ -22,8 +22,12 @@ interface VideoPlayerSharedProps {
     style?: CSSProperties;
     /** Accessible name for the player region. */
     ariaLabel?: string;
+    /** Restart from the beginning instead of showing the replay affordance. Saved videos only. */
+    loop?: boolean;
     onComplete?: (video: Video) => void;
     onError?: (error: Error) => void;
+    /** Fires when the scene under the playhead changes, including on a loop wrap. */
+    onSceneChange?: (scene: VideoScene, index: number) => void;
 }
 type VideoPlayerProps = VideoPlayerSharedProps & ({
     video: Video;

package/dist/react.js

@@ -29,7 +29,7 @@ import "./chunk-2E6T633S.js";
 import {
   VideoFrame,
   getDimensions
-} from "./chunk-HXSV6RHF.js";
+} from "./chunk-N3KUA7VP.js";
 import {
   fontStack
 } from "./chunk-XWWLKRNU.js";
@@ -211,8 +211,10 @@ function VideoPlayerRuntime({
   className,
   style,
   ariaLabel = "Video response",
+  loop = false,
   onComplete,
   onError,
+  onSceneChange,
   onStateChange
 }) {
   const [reducedMotion, setReducedMotion] = useState(
@@ -238,10 +240,13 @@ function VideoPlayerRuntime({
   const timeRef = useRef(currentTime);
   const audioRef = useRef(null);
   const introStartedAtRef = useRef(autoStartGeneration ? performance.now() : null);
-  const callbacksRef = useRef({ onComplete, onError, onStateChange });
+  const callbacksRef = useRef({ onComplete, onError, onSceneChange, onStateChange });
+  const loopRef = useRef(loop);
+  const sceneIndexRef = useRef(-1);
   stateRef.current = state;
   timeRef.current = currentTime;
-  callbacksRef.current = { onComplete, onError, onStateChange };
+  callbacksRef.current = { onComplete, onError, onSceneChange, onStateChange };
+  loopRef.current = loop;
   const primeSoundtrack = () => {
     const audio = audioRef.current;
     if (!audio || audio.dataset.audioOutput) return;
@@ -367,25 +372,50 @@ function VideoPlayerRuntime({
       const config2 = current.config;
       const delta = Math.max(0, (now - previous) / 1e3);
       previous = now;
+      const settled = current.status === "complete" || current.status === "error" || current.status === "aborted";
+      const looping = loopRef.current && settled;
+      let wrapped = false;
       if (config2?.scenes.length) {
         const duration3 = getVideoDuration(config2);
-        const nextTime = Math.min(timeRef.current + delta, duration3);
+        const raw = timeRef.current + delta;
+        let nextTime;
+        if (looping && duration3 > 0 && raw >= duration3) {
+          nextTime = raw % duration3;
+          wrapped = true;
+        } else {
+          nextTime = Math.min(raw, duration3);
+        }
         if (nextTime !== timeRef.current) {
           timeRef.current = nextTime;
           setCurrentTime(nextTime);
         }
         const audio = audioRef.current;
         if (audio && (current.status === "complete" || current.status === "error")) {
+          if (wrapped) {
+            audio.currentTime = 0;
+            if (audio.paused) void audio.play().catch(Boolean);
+          }
           const fadeSeconds = Math.max(0, (config2.audio?.fadeOutMs ?? 3e3) / 1e3);
           const remaining = Math.max(0, duration3 - nextTime);
           const baseVolume = config2.audio?.volume ?? 1;
           audio.volume = fadeSeconds > 0 ? baseVolume * Math.min(1, remaining / fadeSeconds) : baseVolume;
-          if (remaining <= 0) audio.pause();
+          if (remaining <= 0 && !looping) audio.pause();
+        }
+        const notify = callbacksRef.current.onSceneChange;
+        if (notify) {
+          if (wrapped) sceneIndexRef.current = -1;
+          const ranges = resolveVideoTimeline(config2);
+          const index = ranges.findIndex((range) => nextTime >= range.start && nextTime < range.end);
+          const resolved = index === -1 && nextTime >= duration3 ? ranges.length - 1 : index;
+          if (resolved !== -1 && resolved !== sceneIndexRef.current) {
+            sceneIndexRef.current = resolved;
+            notify(ranges[resolved].scene, resolved);
+          }
         }
       }
-      const terminal2 = current.status === "complete" || current.status === "error" || current.status === "aborted";
+      const terminal2 = settled;
       const duration2 = current.config ? getVideoDuration(current.config) : 0;
-      if (!terminal2 || timeRef.current < duration2) frame = requestAnimationFrame(tick);
+      if (!terminal2 || looping || timeRef.current < duration2) frame = requestAnimationFrame(tick);
       else setIsPlaying(false);
     };
     frame = requestAnimationFrame(tick);
@@ -470,7 +500,7 @@ function VideoPlayerRuntime({
   const displayConfig = config && config.orientation !== orientation ? { ...config, orientation } : config;
   const duration = config ? getVideoDuration(config) : 0;
   const terminal = state.status === "complete" || state.status === "error" || state.status === "aborted";
-  const ended = terminal && duration > 0 && currentTime >= duration - 1e-3;
+  const ended = !loop && terminal && duration > 0 && currentTime >= duration - 1e-3;
   const generationIntroWaiting = Boolean(playbackMode && stream && !generationIntroComplete);
   const firstSceneRange = config ? resolveVideoTimeline(config)[0] : void 0;
   const hasSuppliedOpening = firstSceneRange?.scene.id === "supplied-opening";

package/dist/server.d.ts

@@ -1,6 +1,6 @@
-import { m as VideoGenerationContext, n as VideoPlanner, o as VideoRequest, k as VideoCapabilities, d as VideoInput, a as VideoAudio, p as VideoSceneValidator, q as VideoTemplatePacing, r as VideoSnapshotRetention, s as VideoResumeCursor, t as VideoSceneValidationContext, g as VideoScene } from './types-CVMb6QEq.js';
-import { b as VideoFinishReason, a as VideoWarning, V as VideoEvent } from './events-tQ0x-VaL.js';
-export { c as VideoWarningCategory } from './events-tQ0x-VaL.js';
+import { n as VideoGenerationContext, o as VideoPlanner, p as VideoRequest, a as VideoCapabilities, j as VideoInput, d as VideoAudio, q as VideoSceneValidator, r as VideoTemplatePacing, s as VideoSnapshotRetention, t as VideoResumeCursor, u as VideoSceneValidationContext, e as VideoScene } from './types-Cg0Onj7l.js';
+import { b as VideoFinishReason, a as VideoWarning, V as VideoEvent } from './events-D_1F6gw5.js';
+export { c as VideoWarningCategory } from './events-D_1F6gw5.js';
 import { S as SceneTemplateMetadata } from './catalog-types-BIhSpOWK.js';
 
 interface VideoProviderUsage {

package/dist/templates.d.ts

@@ -1,9 +1,9 @@
-import { I as InferTemplateJsonSchema, S as SceneTemplateProps, a as SceneTemplate } from './kit-DlUSg8lA.js';
-export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-DlUSg8lA.js';
+import { I as InferTemplateJsonSchema, S as SceneTemplateProps, a as SceneTemplate } from './kit-DLeCr3d0.js';
+export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-DLeCr3d0.js';
 import { ComponentType } from 'react';
 import { d as TemplateJsonSchema, S as SceneTemplateMetadata } from './catalog-types-BIhSpOWK.js';
 export { T as TemplateFamily, c as TemplateTimingMetadata, e as TemplateTransitionTiming } from './catalog-types-BIhSpOWK.js';
-import './types-CVMb6QEq.js';
+import './types-Cg0Onj7l.js';
 
 interface TemplateExample<Variables extends Record<string, unknown> = Record<string, unknown>> {
     name: string;

package/dist/test.d.ts

@@ -1,5 +1,5 @@
-import { g as VideoScene, f as VideoOrientation, h as VideoStyle, V as Video, a as VideoAudio, d as VideoInput } from './types-CVMb6QEq.js';
-import { a as VideoWarning, b as VideoFinishReason } from './events-tQ0x-VaL.js';
+import { e as VideoScene, b as VideoOrientation, V as VideoStyle, c as Video, d as VideoAudio, j as VideoInput } from './types-Cg0Onj7l.js';
+import { a as VideoWarning, b as VideoFinishReason } from './events-D_1F6gw5.js';
 
 type MockVideoStreamPart = {
     type: "scene.add";

package/dist/{types-CVMb6QEq.d.ts → types-Cg0Onj7l.d.ts}

@@ -209,4 +209,4 @@ interface VideoSnapshotRetention {
     suppliedMediaUrls?: boolean;
 }
 
-export { type Video as V, type VideoAudio as a, type VideoBackground as b, type VideoBrand as c, type VideoInput as d, type VideoKnowledgeMode as e, type VideoOrientation as f, type VideoScene as g, type VideoStyle as h, type VideoStyleOptions as i, type VideoSuppliedMedia as j, type VideoCapabilities as k, VIDEO_PROTOCOL_VERSION as l, type VideoGenerationContext as m, type VideoPlanner as n, type VideoRequest as o, type VideoSceneValidator as p, type VideoTemplatePacing as q, type VideoSnapshotRetention as r, type VideoResumeCursor as s, type VideoSceneValidationContext as t };
+export { type VideoStyle as V, type VideoCapabilities as a, type VideoOrientation as b, type Video as c, type VideoAudio as d, type VideoScene as e, VIDEO_PROTOCOL_VERSION as f, type VideoBrandInput as g, type VideoBrand as h, type VideoBackground as i, type VideoInput as j, type VideoKnowledgeMode as k, type VideoStyleOptions as l, type VideoSuppliedMedia as m, type VideoGenerationContext as n, type VideoPlanner as o, type VideoRequest as p, type VideoSceneValidator as q, type VideoTemplatePacing as r, type VideoSnapshotRetention as s, type VideoResumeCursor as t, type VideoSceneValidationContext as u };

package/docs/getting-started.md

@@ -5,7 +5,7 @@
 Install VanillaSky:
 
 ```bash
-npm install @vanillaskyai/video@0.3.3 ai @ai-sdk/openai
+npm install @vanillaskyai/video@0.4.0 ai @ai-sdk/openai
 ```
 
 Set your provider key in `.env.local` (never commit it):
@@ -50,7 +50,7 @@ sets its marker only for `next dev`, and it accepts only localhost. Every
 production request is denied. Replace it with your real session validation
 before deploying. For literal files and commands,
 use the tested
-[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.3.3/examples/nextjs-quickstart).
+[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.4.0/examples/nextjs-quickstart).
 
 `model` can come from any AI SDK provider, registry, gateway, compatible API,
 or custom implementation. The application can choose a cheaper or faster model

package/docs/integrate-nextjs.md

@@ -5,7 +5,7 @@
 Install VanillaSky and one AI SDK provider:
 
 ```bash
-npm install @vanillaskyai/video@0.3.3 ai @ai-sdk/openai
+npm install @vanillaskyai/video@0.4.0 ai @ai-sdk/openai
 ```
 
 Create an ignored `.env.local`:
@@ -74,7 +74,7 @@ requests; replace it with your application's session validation before
 deploying.
 
 The copy-and-run app is in the
-[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.3.3/examples/nextjs-quickstart).
+[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.4.0/examples/nextjs-quickstart).
 
 For another LLM, replace `openai(...)` with the matching AI SDK model. The route
 shape and React code stay the same. See [Provider integration](provider-integration.md)

package/docs/live-channels.md

@@ -0,0 +1,146 @@
+[← Documentation home](../README.md) · [Previous: Persistence and replay](persistence.md) · [Next: Streaming protocol →](streaming-protocol.md)
+
+# Live channels
+
+A live channel is a video that plays continuously and rebuilds itself on a
+schedule: a market ticker, a news wall, a status board in an office, a loop
+behind a conference stand. Nobody presses play, nobody watches from the start,
+and the content changes on its own.
+
+This is a different shape from a generated response. A response is produced for
+one person, once, in reply to something they asked. A channel is produced ahead
+of time for nobody in particular, and then played to whoever is looking.
+
+That difference is what makes it cheap. Playback of a saved `Video` performs no
+generation request and no model call — the player is DOM and CSS advanced by a
+`requestAnimationFrame` clock — so a channel that loops all day costs exactly as
+much as a channel that loops once. All of the cost lives in building the
+configuration, which happens on your schedule rather than per viewer.
+
+## The shape
+
+```
+scheduled job                       browser
+─────────────                       ───────
+fetch your data          ┌────────► fetch the stored Video
+map it to scenes         │          parseVideo(...)
+parseVideo(...)  ────────┘          <VideoPlayer video={...} loop />
+store the JSON                      plays forever
+```
+
+The job owns the data and the mapping. The player owns nothing but playback.
+
+## Play without stopping
+
+Pass `loop` alongside a saved video. The player restarts from the beginning
+instead of showing its replay affordance, and keeps its soundtrack in step.
+
+<!-- verify:live-channel-example:start -->
+```tsx
+import { useEffect, useState } from "react";
+import { parseVideo, type Video, type VideoScene } from "@vanillaskyai/video";
+import { VideoPlayer } from "@vanillaskyai/video/react";
+
+export function Channel({ endpoint }: { endpoint: string }) {
+  const [video, setVideo] = useState<Video | undefined>(undefined);
+  const [onScreen, setOnScreen] = useState<VideoScene | undefined>(undefined);
+
+  const load = async () => {
+    const stored: unknown = await fetch(endpoint).then((response) => response.json());
+    setVideo(parseVideo(stored));
+  };
+
+  useEffect(() => { void load(); }, []);
+  if (!video) return null;
+
+  return <>
+    <VideoPlayer
+      video={video}
+      loop
+      autoPlay
+      playbackMode="muted-autoplay"
+      onSceneChange={(scene, index) => {
+        setOnScreen(scene);
+        // Wrapping back to the start is a natural moment to pick up a rebuild,
+        // so a screen left running all day never serves a stale channel.
+        if (index === 0) void load();
+      }}
+    />
+    <p>{onScreen ? onScreen.templateId : "starting"}</p>
+  </>;
+}
+```
+<!-- verify:live-channel-example:end -->
+
+`loop` applies to saved videos. A streaming response still ends when the stream
+ends, because there is nothing to loop back to until it completes.
+
+## Follow what is on screen
+
+`onSceneChange` fires whenever the scene under the playhead changes, and again
+on index `0` each time a loop wraps. Use it to drive anything that has to stay
+in step with the video: a caption rail, a source panel, chapter markers, an
+analytics event per scene.
+
+Do not run your own timer for this. A parallel clock drifts from the player's
+as soon as playback is paused, throttled in a background tab, or delayed by a
+slow asset, and the drift is silent.
+
+`onComplete` is not an alternative here: it reports the end of a *stream*, so it
+never fires for a saved video.
+
+## Build the configuration yourself
+
+A channel's scenes usually come from your own data rather than from a model.
+`resolveVideoBrand` fills a partial brand with the documented defaults, so a
+hand-authored `Video` satisfies `parseVideo` without copying a defaults blob
+into your application:
+
+```ts
+import { parseVideo, resolveVideoBrand } from "@vanillaskyai/video";
+
+const channel = parseVideo({
+  schemaVersion: "0.1",
+  orientation: "landscape",
+  scenes: rows.map((row, index) => ({
+    id: `row-${index}`,
+    templateId: "bigNumber",
+    variables: { texts: row.label, value: row.value, unit: row.unit },
+    timing: { fixedDuration: 5 },
+  })),
+  style: { brand: resolveVideoBrand({ name: "Acme", background: "midnight" }) },
+});
+```
+
+Validate with `parseVideo` inside the job, before storing. A channel that fails
+validation in the browser is a channel nobody can watch; one that fails in the
+job can simply leave the previous version in place.
+
+## Keep motion independent of scene length
+
+Templates receive `sceneDuration`. Express motion in seconds against it rather
+than as a fraction of `progress`, or lengthening a scene to give viewers more
+reading time will stretch its animation instead and give them none.
+
+## Practical notes
+
+- **Rebuild on a schedule, not per request.** Viewers should read a stored
+  configuration. If every viewer triggers generation, a channel becomes the most
+  expensive surface you own rather than the cheapest.
+- **Never replace a good channel with a broken one.** Validate first, and on
+  failure leave the previous configuration in place.
+- **Autoplay needs `playbackMode="muted-autoplay"`.** Browsers refuse unmuted
+  autoplay, and a channel has no one present to click.
+- **Host your media.** Loops re-request assets over long sessions; serving them
+  from your own origin keeps a content policy simple and avoids depending on
+  someone else's CDN.
+- **Long channels are ordinary videos.** Ten minutes of scenes is one `Video`
+  with more entries in `scenes`; there is no separate playlist concept.
+
+## Related
+
+- [Persistence and replay](persistence.md) — the storage boundary these
+  configurations pass through
+- [Custom templates](custom-templates.md) — templates for your own data shapes
+- [Responsive orientation](responsive-orientation.md) — the same channel on a
+  portrait screen

package/docs/persistence.md

@@ -1,4 +1,4 @@
-[← Documentation home](../README.md) · [Previous: Core concepts](concepts.md) · [Next: Streaming protocol →](streaming-protocol.md)
+[← Documentation home](../README.md) · [Previous: Core concepts](concepts.md) · [Next: Live channels →](live-channels.md)
 
 # Persistence and replay
 

package/docs/streaming-protocol.md

@@ -1,4 +1,4 @@
-[← Documentation home](../README.md) · [Previous: Core concepts](concepts.md) · [Next: Security →](security.md)
+[← Documentation home](../README.md) · [Previous: Live channels](live-channels.md) · [Next: Security →](security.md)
 
 # Streaming protocol
 

package/examples/nextjs-quickstart/package.json

@@ -9,7 +9,7 @@
   },
   "dependencies": {
     "@ai-sdk/openai": "^4.0.42",
-    "@vanillaskyai/video": "0.3.3",
+    "@vanillaskyai/video": "0.4.0",
     "ai": "^7.0.66",
     "next": "16.3.1",
     "react": "19.2.8",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Open-source video response SDK for personalized AI applications.",
   "keywords": [
     "generative-video",