@vanillaskyai/video 0.10.15 → 0.10.17

package/CHANGELOG.md

@@ -4,6 +4,18 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.17
+
+- Let video playback prepare without waiting for an optional poster, while retaining actual video-frame and narration readiness checks.
+- Guide shorter, useful spoken openings and compact streamed briefs, with clearer direct answers, comparisons, and narration-aligned actions.
+
+## 0.10.16
+
+- Start the first fully prepared scene without waiting for an eight-second startup buffer, while preserving narration and visual readiness.
+- Keep generated narration alive when a superseded playback attempt rejects after pause and resume.
+- Give ending suggestions larger responsive cards with complete labels, including narrow embedded players.
+- Match simple singular and plural stock subjects in the starter without discarding required subjects or exclusions.
+
 ## 0.10.15
 
 - Recover a mislabeled first chat brief only when its complete authored content validates, preserving its shots and ending. Keep malformed JSON and incomplete or later records rejected.

package/dist/react.js

@@ -1385,18 +1385,6 @@ function createSceneTimeline(options) {
 }
 
 // src/player/scene-readiness.ts
-var READY_AHEAD_SECONDS = 8;
-function canStartPreparedSequence(scenes, complete) {
-  let seconds = 0;
-  let count = 0;
-  for (const scene of scenes) {
-    if (!scene) break;
-    count += 1;
-    seconds += scene.timing.fixedDuration ?? 0;
-    if (seconds >= READY_AHEAD_SECONDS) return true;
-  }
-  return complete && count > 0 && count === scenes.length;
-}
 function preparedSceneDuration(scene, spokenSeconds, metadata) {
   const timing = metadata?.timing;
   const authored = (timing?.revealSeconds ?? 0) + (timing?.holdSeconds ?? 0) + (timing?.exitSeconds ?? 0);
@@ -1513,9 +1501,7 @@ async function prepareSceneMedia(variables, signal) {
   const url = typeof variables.mediaUrl === "string" ? variables.mediaUrl.trim() : "";
   if (!url || variables.mediaType === "gradient") return "graphic";
   const video = variables.mediaType === "video" || /\.(mp4|webm|mov)(?:[?#]|$)/i.test(url);
-  const poster = typeof variables.mediaPoster === "string" ? variables.mediaPoster.trim() : "";
-  if (video && !poster) return "awaiting-video-frame";
-  let posterFailed = false;
+  if (video) return "awaiting-video-frame";
   await new Promise((resolve, reject) => {
     const image = new Image();
     let settled = false;
@@ -1538,13 +1524,10 @@ async function prepareSceneMedia(variables, signal) {
       void (image.decode ? image.decode() : Promise.resolve()).then(() => finish(), () => finish(new Error("Could not prepare scene image")));
     };
     image.onerror = () => finish(new Error("Could not prepare scene image"));
-    image.src = video ? poster : url;
+    image.src = url;
     if (image.complete && image.naturalWidth > 0) image.onload(new Event("load"));
-  }).catch((error) => {
-    if (!video || signal.aborted) throw error;
-    posterFailed = true;
   });
-  return video ? posterFailed ? "awaiting-video-frame" : "poster-bridge" : "image";
+  return "image";
 }
 
 // src/video-chat/voice.ts
@@ -1586,6 +1569,18 @@ function createVideoChatVoice(options = {}) {
   let disposed = false;
   let generatedSpeechUnavailable = false;
   let playbackFailure;
+  let playbackAttempt = 0;
+  const playGenerated = (element, fail) => {
+    const attempt = ++playbackAttempt;
+    const reject = () => {
+      if (attempt === playbackAttempt && !held && sounding === element) fail?.();
+    };
+    try {
+      void element.play().catch(reject);
+    } catch {
+      reject();
+    }
+  };
   const notifyFallback = () => {
     try {
       void Promise.resolve(options.onFallback?.()).catch(() => void 0);
@@ -1698,6 +1693,7 @@ function createVideoChatVoice(options = {}) {
       return { seconds: line.seconds, ...line.source === "generated" && line.measured === true ? { supportsOffsets: true } : {} };
     },
     pause() {
+      playbackAttempt++;
       held = true;
       sounding?.pause();
       globalThis.speechSynthesis?.pause();
@@ -1712,12 +1708,7 @@ function createVideoChatVoice(options = {}) {
         } catch {
         }
       }
-      if (sounding) {
-        const fail = playbackFailure;
-        void sounding.play().catch(() => {
-          if (!held) fail?.();
-        });
-      }
+      if (sounding) playGenerated(sounding, playbackFailure);
       if (!silent) globalThis.speechSynthesis?.resume();
     },
     setMuted(muted) {
@@ -1848,13 +1839,7 @@ function createVideoChatVoice(options = {}) {
           element.onended = finish;
           element.onerror = fail;
           signal.addEventListener("abort", stop, { once: true });
-          try {
-            if (!held) void element.play().catch(() => {
-              if (!held) fail();
-            });
-          } catch {
-            fail();
-          }
+          if (!held) playGenerated(element, fail);
         });
       } catch {
         playbackFailed = true;
@@ -2372,7 +2357,7 @@ function useVideoChatSession(options = {}) {
         return;
       }
       if (!timeline) {
-        if (!style || openingActive || heldRef.current || available === appended || !canStartPreparedSequence(ready.slice(0, available), planDone)) return;
+        if (!style || openingActive || heldRef.current || available === appended) return;
         timeline = createSceneTimeline({ style, orientation });
         timelineRef.current = timeline;
         openingController.abort(new DOMException("Opening replaced by response", "AbortError"));

package/dist/server.js

@@ -1217,18 +1217,21 @@ function createVideoChatResponseInstructions(generatedVideoAvailable, openingAlr
   return [
     'Use the exact record type "answer" for the first brief and "shot" for developing beats. Output JSON records only, with no prose outside them, including when explaining a limitation.',
     "Write a complete, intentful video answer as newline-delimited JSON. Match the user's form and tone; mixed intents can combine directions.",
-    `First write one brief: {"type":"answer","intent":"explanation|story|comedy|imagination|practical","opening":"a short inviting spoken introduction of 6\u20139 words","subject":"literal visual subject","development":"the essential development of this answer","visualDirection":"consistent subjects, appearance and visual approach","ending":{"title":"short meaningful chapter title, at most 65 characters","narration":"the authored payoff","subject":"literal subject","action":"visible action or change","durationSec":${clipDurationSec},"continuity":"cut|continue"}}.`,
+    `First write one brief: {"type":"answer","intent":"explanation|story|comedy|imagination|practical","opening":"one useful spoken line of 4\u20137 ordinary words","subject":"literal visual subject","development":"the essential development of this answer","visualDirection":"consistent subjects, appearance and visual approach","ending":{"title":"short meaningful chapter title, at most 65 characters","narration":"the authored payoff","subject":"literal subject","action":"visible action or change","durationSec":${clipDurationSec},"continuity":"cut|continue"}}.`,
+    "The opening should take roughly 2\u20133 seconds at a natural pace: give the core answer, a useful starting cue, or the story's immediate situation. No greeting, topic announcement, promise to explain, or description of loading. Never compress away an essential qualifier just to hit the word target.",
     `Then stream each developing shot on its own line: {"type":"shot","title":"short meaningful chapter title, at most 65 characters","narration":"the exact spoken beat","subject":"2\u20138 literal filmable words, at most 80 characters","action":"concrete subject, action or visible change and useful framing","durationSec":${clipDurationSec},"continuity":"cut|continue"}.`,
     `The selected footage mode is ${mode === "pexels" ? "Pexels stock search: use literal filmable subjects; never imply stock proves a mechanism or depicts fictional events exactly" : `AI video, with at most ${generatedVideoAvailable ? maxGeneratedVideos : 0} generation attempts`}. Missing footage becomes the authored chapter title, with complete narration. Never truncate already-authored narration when footage fails. The host selects providers; do not make source choices.`,
     ...mode === "cinematic" ? [generatedVideoAvailable && maxGeneratedVideos > 0 ? `Plan at most ${maxGeneratedVideos} generated-video beats in total, including the saved ending. Use at most ${maxGeneratedVideos - 1} developing shot records; the ending uses the remaining beat. The opening chapter does not consume a generated clip. Before writing, choose a concise, complete treatment that fits this budget: combine related ideas, preserve essential facts and qualifiers, and finish the requested answer. Do not plan an extra chapter tail simply because generation attempts will run out.${maxGeneratedVideos === 1 ? " Put the complete answer in the saved ending, set development to an empty string, and emit no developing shot records." : ""}` : "No generated-video attempts are available; plan a complete chapter-led answer with a useful ending. Do not omit the answer to satisfy a zero clip budget."] : [],
     ...mode === "pexels" ? ["Stock queries must retain the essential subject, activity and distinguishing equipment in the shot's subject field, within its word limit. That field alone is the search query; action and visualDirection do not refine it. Prefer common observable actions with usable framing. Do not replace the required actor or activity with scenery, a different sport or a loosely related setting. Preserve fictional or comic narration, but do not depend on stock showing an exact invented expression or sequence; choose an illustrative action that supports the beat."] : [],
     ...mode === "pexels" ? ['Include stockSelection on every shot and the saved ending when the essential subject is known: "stockSelection":{"subject":"essential actor or object category","activity":"optional literal activity","equipment":"optional distinguishing equipment","exclude":["optional contradictory subject or activity"]}. Each phrase must be 1\u20134 words and at most 48 characters; exclude has at most 3 phrases. The essential subject is separate from the setting: do not use scenery, mood, camera framing or incidental appearance as the actor. Keep the search query broad enough to find footage; the optional hint helps select results without substituting a different actor or task. Use exclusions only for actual contradictions, not every detail absent from the story. Omit unknown fields or the whole hint rather than inventing an anchor. This is selection guidance, not verification that footage depicts the exact narration.'] : [],
+    "Keep development to one concise sentence and visualDirection to the few details needed for consistency. Emit the complete brief, then the first developing shot immediately when developing shots are needed and allowed by the budget; otherwise end after the brief. Continue the same stream without an outline, recap or second planning pass. The saved ending must still contain the complete payoff before the brief is emitted.",
     "For a very short answer whose ending alone fulfills the request, development may be empty and no developing shots are needed. Otherwise, develop the essential content before the ending.",
     "The brief's ending is saved and played after your developing shots. Do not repeat it as a shot. Stop writing after the last developing shot. No technical events, identifiers, template choices, media providers, URLs or unlisted fields.",
     "Every shot uses moving footage with separate narration and subtitles. Generated footage is silent: do not ask its subjects to speak or render words. No headline cards or on-screen explanatory text.",
     `Each clip has at most ${clipDurationSec} seconds. Write spoken beats that fit naturally, usually ${Math.floor(clipDurationSec * 1.6)}\u2013${Math.floor(clipDurationSec * 2)} words per shot. Split longer ideas across purposeful shots, preserving facts and qualifiers. Never truncate a claim to meet a word target. Use only the shots needed within the total duration, including the ending; do not pad to a fixed count.`,
-    "Identify the full answer and its ending before developing shots. Each action must support what is said: camera movement alone is not progression. Vary scale, viewpoint and meaningful details while keeping subjects consistent.",
-    "Explanations: clarify the actual causal mechanism, separating physical cause from a metaphor. Generated cutaways and animation illustrate ideas; they are not factual evidence. Preserve uncertainty, quantities and conditions; never invent evidence or quotations.",
+    "Identify the full answer and its ending before developing shots. Each shot should carry one clear action or change, timed to the narration of that beat; do not describe an outcome before its shot. Use framing that lets the viewer see the relevant action, not just its setting. Each action must support what is said: camera movement alone is not progression. Vary scale, viewpoint and meaningful details while keeping subjects consistent.",
+    "Explanations: answer the actual question first, then show the essential causal link rather than a tour of the topic. Clarify the actual causal mechanism, separating physical cause from a metaphor. Generated cutaways and animation illustrate ideas; they are not factual evidence. Preserve uncertainty, quantities and conditions; never invent evidence or quotations.",
+    "Comparisons and choices: Compare the same criteria for both alternatives, using only supported or supplied differences. Finish with the requested choice and the condition that makes it appropriate; if evidence is insufficient, say what is missing. Do not invent scores, advantages or a winner. Use explanation or practical intent as appropriate, not a new record type.",
     "Stories: portray characters making choices and experiencing consequences; use consistent character descriptions and an earned resolution, not a promised next scene.",
     "Comedy: establish the premise, time the visual or spoken reveal, allow a reaction beat, and stop on the payoff without explaining the joke.",
     "Imagination: make the impossible action concrete, establish the world's internal rules and keep its imagery consistent. Do not replace imagination with an explanation of it.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.10.15",
+  "version": "0.10.17",
   "description": "Open-source voice-and-video chat SDK for AI applications.",
   "keywords": [
     "video-chat",

package/starters/video-chat/package.json

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@vanillaskyai/video": "0.10.15",
+    "@vanillaskyai/video": "0.10.17",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "@ai-sdk/anthropic": "^3.0.0",

package/starters/video-chat/stock.ts

@@ -17,6 +17,11 @@ const cache = new Map<string, { expires: number; media: StockVideo | null }>();
 const words = (value: string): string[] => value.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
 const ignored = new Set(['a','an','the','in','on','at','of','with','and','to']);
 const terms = (value: string) => words(value).filter(word => !ignored.has(word));
+// Only simple English -s forms; avoid aggressive stemming and ambiguous endings.
+function wordForm(word: string) {
+  return /^[a-z]{3,}s$/.test(word) && !/(?:ss|us|is|ies)$/.test(word) && word !== 'news'
+    ? word.slice(0, -1) : word;
+}
 function selectionHint(value: unknown) {
   const phrase = (input: unknown) => {
     if (typeof input !== 'string') return undefined;
@@ -48,7 +53,7 @@ export async function findStockFootage(query: string, orientation: VideoOrientat
   const normalized = query.trim().toLowerCase().replace(/\s+/g, " ");
   const tokens = words(normalized);
   const selection = selectionHint(rawSelection);
-  const key = JSON.stringify({version: 2, orientation, query: normalized, selection});
+  const key = JSON.stringify({version: 3, orientation, query: normalized, selection});
   const apiKey = process.env.PEXELS_API_KEY;
   if (!apiKey || !tokens.length || normalized.length > 80 || tokens.length > 8) return null;
   const existing = cache.get(key);
@@ -66,10 +71,10 @@ export async function findStockFootage(query: string, orientation: VideoOrientat
     const slug = new URL(video.url).pathname.replace(/^\/video\//, "");
     const title = typeof video.title === "string" ? video.title : "";
     const tags = Array.isArray(video.tags) ? video.tags.filter((tag): tag is string => typeof tag === "string").join(" ") : "";
-    const subject = words(`${slug} ${title} ${typeof video.description === "string" ? video.description : ""} ${tags}`).filter(token => !/^\d+$/.test(token));
-    let matches = tokens.filter(token => subject.includes(token)).length;
+    const subject = words(`${slug} ${title} ${typeof video.description === "string" ? video.description : ""} ${tags}`).filter(token => !/^\d+$/.test(token)).map(wordForm);
+    let matches = tokens.filter(token => subject.includes(wordForm(token))).length;
     if (selection && subject.length) {
-      const covers = (phrase: string) => terms(phrase).every(word => subject.includes(word));
+      const covers = (phrase: string) => terms(phrase).every(word => subject.includes(wordForm(word)));
       if (!covers(selection.subject) || selection.exclude?.some(covers)) continue;
       // Query context breaks equal hint matches without outweighing a hint.
       const contextScore = matches / (tokens.length + 1);

package/styles/video-chat.css

@@ -348,12 +348,15 @@
 
 .vanillasky-video-chat .ending-body {
   position: absolute;
-  inset: auto 0 0;
+  inset: 96px 0 180px;
   display: flex;
   flex-direction: column;
   align-items: flex-start;
   gap: clamp(0.5rem, 1.4cqh, 0.9rem);
-  padding: 0 clamp(1.25rem, 4cqw, 3.5rem) clamp(1.25rem, 4cqh, 2.5rem);
+  padding: 12px clamp(20px, 3.5cqw, 56px);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  justify-content: safe flex-end;
   color: oklch(1 0 0);
 }
 
@@ -367,9 +370,13 @@
   text-shadow: 0 1px 3px oklch(0.14 0.05 265 / 70%);
 }
 
-.vanillasky-video-chat .ending .cards { margin-top: 0; }
-
-.vanillasky-video-chat .ending .cards button { width: clamp(8rem, 15.5cqw, 12rem); }
+.vanillasky-video-chat .ending .cards {
+  margin-top: 0;
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  flex-shrink: 0;
+  overflow: visible;
+}
 
 .vanillasky-video-chat .ending .card-dots { align-self: flex-start; margin-left: -0.35rem; }
 
@@ -410,7 +417,6 @@
   animation: vanillasky-video-chat-fade-in 320ms ease both;
 }
 
-
 @keyframes vanillasky-video-chat-fade-in { from { opacity: 0; } to { opacity: 1; } }
 
 @keyframes vanillasky-video-chat-rise { from { opacity: 0; transform: translate(-50%, 6px); } to { opacity: 1; transform: translate(-50%, 0); } }
@@ -600,7 +606,6 @@
 
 .vanillasky-video-chat .panel .error { pointer-events: auto; width: min(560px, 100%); background: var(--vs-bg); }
 
-
 .vanillasky-video-chat .welcome { background: var(--vs-media-ground); }
 
 .vanillasky-video-chat .welcome .frame-media { max-width: none; max-height: none; object-fit: cover; }
@@ -625,10 +630,6 @@
 
 .vanillasky-video-chat .card-dots { display: none; }
 
-.vanillasky-video-chat .ending-body { padding: 0 var(--vs-media-gutter) 190px; }
-
-.vanillasky-video-chat .ending .cards { margin-top: 0; }
-
 .vanillasky-video-chat .ending-label { font-size: 15px; margin-bottom: 6px; }
 
 @media (max-width: 700px) {
@@ -643,15 +644,13 @@
   .vanillasky-video-chat .cards { gap: 12px; width: calc(100% + 20px); max-width: calc(100% + 20px); padding: 12px 20px 12px 12px; }
   .vanillasky-video-chat .cards button { width: 172px; aspect-ratio: .95; }
   .vanillasky-video-chat .card-prompt { font-size: 14px; padding: 14px; }
-  .vanillasky-video-chat .ending-body { padding: 0 20px 190px; }
-  .vanillasky-video-chat .ending .cards button { width: 165px; aspect-ratio: 1.15; }
+
 }
 
 @media (max-height: 650px) and (min-width: 701px) {
   .vanillasky-video-chat .welcome-body { padding-top: 110px; padding-bottom: 118px; }
   .vanillasky-video-chat .welcome-title { font-size: clamp(32px, 4vw, 54px); }
   .vanillasky-video-chat .cards button { width: 160px; }
-  .vanillasky-video-chat .ending-body { padding-bottom: 160px; }
 }
 
 @media (max-height: 650px) and (max-width: 700px) {
@@ -709,8 +708,6 @@
 
 .vanillasky-video-chat .expanded-captions .eyebrow { color: var(--vs-media-muted); }
 
-
-
 .vanillasky-video-chat .dock-hint { position: absolute; inset: auto 0 7px; text-align: center; margin: 0; color: var(--vs-media-muted); font-size: 11px; line-height: 16px; }
 
 .vanillasky-video-chat .panel-inner:has(.dock-hint) { padding-bottom: max(38px, calc(env(safe-area-inset-bottom) + 20px)); }
@@ -784,7 +781,6 @@
 
 .vanillasky-video-chat .composer-meta:empty { display: none; }
 
-
 .vanillasky-video-chat .composer-meta .error { width: auto; }
 
 @media (max-width: 700px) {
@@ -922,7 +918,6 @@
 .vanillasky-video-chat .developer-links button { width: 100%; border: 0; background: transparent; text-align: left; cursor: pointer; font-family: inherit; }
 .vanillasky-video-chat .developer-about p { margin: 0; padding: 2px 12px 12px; color: var(--vs-fg-muted); font-size: 12px; line-height: 1.6; }
 
-
 .vanillasky-video-chat .history { display: grid; gap: 4px; }
 
 .vanillasky-video-chat .history .section-label { padding-top: 8px; padding-bottom: 5px; }
@@ -943,7 +938,6 @@
 
 .vanillasky-video-chat .history-row small { display: block; margin-top: 4px; font-size: 11px; font-weight: 400; color: #aeb2c7; }
 
-
 @media (max-width: 700px) {
   .vanillasky-video-chat .sheet-popover { right: 12px; width: min(360px, calc(100% - 24px)); max-height: calc(100dvh - 102px); padding: 16px; }
   .vanillasky-video-chat .popover-heading .round { width: 44px; height: 44px; }
@@ -1028,7 +1022,6 @@
   }
 }
 
-
 /* Caption controls float outside the reading measure, so the complete cue
    keeps the same width when controls appear or disappear. */
 .vanillasky-video-chat .caption-actions {
@@ -1085,3 +1078,32 @@
 .vanillasky-video-chat .media-credit { color: var(--vs-fg); font-size: 11px; margin-left: 12px; text-underline-offset: 3px; }
 @keyframes vanillasky-chapter-enter { from { opacity: 0; } to { opacity: 1; } }
 @media (prefers-reduced-motion: reduce) { .vanillasky-video-chat .opening-chapter { animation: none; } }
+
+.vanillasky-video-chat .ending .cards li { min-width: 0; }
+
+.vanillasky-video-chat .ending .cards button {
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-end;
+  width: 100%;
+  height: 100%;
+  min-height: 180px;
+  aspect-ratio: auto;
+}
+
+.vanillasky-video-chat .ending .card-prompt {
+  position: relative;
+  inset: auto;
+  overflow-wrap: anywhere;
+  font-size: clamp(14px, 1.2vw, 18px);
+  line-height: 1.4;
+}
+
+@container (min-width: 1200px) {
+  .vanillasky-video-chat .ending .cards { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+  .vanillasky-video-chat .ending .cards button { min-height: 210px; }
+}
+
+@media (max-height: 650px) {
+  .vanillasky-video-chat .ending-body { inset-block: 80px 180px; }
+}