@vanillaskyai/video 0.10.8 → 0.10.9

package/CHANGELOG.md

@@ -4,6 +4,14 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.9
+
+- Use essential subject hints and explicit exclusions when selecting starter Pexels footage, and isolate cached selections by those hints. Metadata-free results remain unverified provider-ranked fallbacks.
+
+- Forward bounded optional subject/activity hints to Pexels resolvers from the existing planning stream, without adding fields to emitted scenes or AI-video requests.
+
+- Clarify beginner instructions and condition-dependent advice, and retain essential subjects and activities in Pexels search planning.
+
 ## 0.10.8
 
 - Reassert a requested pause if native video playback starts late, preserving footage during delayed narration and keeping viewer pauses in place.

package/dist/server.js

@@ -895,6 +895,21 @@ var object = (value) => value && typeof value === "object" && !Array.isArray(val
 function text(value, maximum) {
   return typeof value === "string" && value.trim().length <= maximum ? value.trim() : "";
 }
+function readStockSelection(value) {
+  const item = object(value);
+  const phrase = (candidate) => {
+    if (typeof candidate !== "string") return;
+    const normalized = candidate.trim().replace(/\s+/gu, " ");
+    if (!normalized || normalized.length > 48 || !/^[\p{L}\p{N} '’-]+$/u.test(normalized)) return;
+    const words = normalized.match(/[\p{L}\p{N}]+/gu) ?? [];
+    return words.length >= 1 && words.length <= 4 ? normalized : void 0;
+  };
+  const subject = phrase(item?.subject);
+  if (!subject) return;
+  const activity = phrase(item?.activity), equipment = phrase(item?.equipment);
+  const exclude = Array.isArray(item?.exclude) && item.exclude.length <= 3 ? item.exclude.map(phrase).filter((value2) => value2 !== void 0) : [];
+  return { subject, ...activity ? { activity } : {}, ...equipment ? { equipment } : {}, ...exclude.length ? { exclude } : {} };
+}
 function chapterSubject(subject) {
   const normalized = subject.replace(/\s+/gu, " ");
   if (normalized.length <= 65) return normalized;
@@ -912,6 +927,7 @@ function readShot(value, clipDurationSec, answerSubject = "") {
   return {
     narration,
     title,
+    stockSelection: readStockSelection(item?.stockSelection),
     subject,
     action: text(item?.action, 600),
     durationSec: typeof item?.durationSec === "number" && Number.isFinite(item.durationSec) ? Math.min(clipDurationSec, Math.max(2, item.durationSec)) : clipDurationSec,
@@ -964,7 +980,7 @@ function createChatShotPlanner(options) {
           return { type: "scene.add", ...closer ? { placement: "closer" } : {}, scene: {
             id: `${context.request.requestId}-shot-${++index}`,
             templateId: "cinemaMedia",
-            variables: { fallbackText: shot.title, mediaType: "video", mediaKeyword: shot.subject, shotDirection: [
+            variables: { ...options.mode === "pexels" && shot.stockSelection ? { stockSelection: shot.stockSelection } : {}, fallbackText: shot.title, mediaType: "video", mediaKeyword: shot.subject, shotDirection: [
               brief?.visualDirection,
               shot.action,
               shot.continuity === "continue" ? "Continue the established subject, setting and action consistently." : "A deliberate new shot; choose framing that reveals this beat.",
@@ -1132,8 +1148,10 @@ function createVideoChatResponseInstructions(generatedVideoAvailable, openingAlr
     `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"}}.`,
     `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. Preserve the full answer rather than shortening it to fit credits. The host selects providers; do not make source choices.`,
+    ...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.'] : [],
     "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 extra fields.",
+    "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.",
@@ -1141,7 +1159,7 @@ function createVideoChatResponseInstructions(generatedVideoAvailable, openingAlr
     "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.",
-    "Practical answers: show usable actions in their necessary order, with framing that makes the method and result visible. Preserve essential steps and relevant safety conditions.",
+    "Practical answers: show usable actions in their necessary order, with framing that makes the method and result visible. Preserve essential steps and relevant safety conditions. Match the requested experience level. For beginners, explain an unavoidable technical term in ordinary words or replace it with an observable action. Make the essential setup and a useful success cue explicit. Qualify advice that depends on equipment, task or conditions instead of presenting one setup as universal. Never add unsupported precision merely to sound instructional.",
     openingAlreadyProvided ? "The supplied opening has already been spoken. Preserve it and begin the body with new content." : "The brief opening is spoken during preparation. The first body shot must develop it rather than repeat its words or claim.",
     "Use continuity=continue when the same subject/action should remain coherent; choose cut for a purposeful new view. Describe recurring subjects consistently. Never assume a different angle or generated depiction proves a factual claim."
   ].join("\n");
@@ -1630,6 +1648,7 @@ function createVideoChatHandler(options) {
       invalidPartBehavior: videoOptions.invalidPartBehavior,
       requireCloser: options.requireCloser ?? true,
       generate: createChatShotPlanner({
+        mode,
         streamText: (context) => {
           lifecycle = getGenerationLifecycleSink(context);
           return videoOptions.streamText(context);

package/package.json

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

package/starters/video-chat/README.md

@@ -66,3 +66,26 @@ work and playback, and failed media becomes the authored chapter.
 The provider names its own model. Override the tested defaults with
 `ANTHROPIC_PLANNER_MODEL`, `ANTHROPIC_NARRATION_MODEL`, or `FAL_VIDEO_MODEL`
 when needed.
+
+### Stock selection hints
+
+In Pexels mode, the same planning stream can supply an optional
+`scene.variables.stockSelection` to the application's media resolver:
+
+```ts
+{ subject: "cyclist", activity: "riding", equipment: "bicycle", exclude: ["motorcycle"] }
+```
+
+`subject` names the essential actor or object separately from the search query's
+setting. `activity`, `equipment` and `exclude` are optional. Each phrase has
+one to four words and at most 48 characters; `exclude` has at most three phrases.
+The SDK validates these fields, drops unknown keys and invalid optional values,
+and omits the whole hint when the essential subject is missing or invalid.
+It never guesses that subject from the first query word.
+
+Adapters can use this hint to prefer matching subjects and reject explicitly
+contradictory metadata while keeping the query broad enough for catalog search.
+Missing metadata remains uncertain, not proof of a match. The hint does not
+verify the depicted action or factual correctness. It is omitted from AI-video
+requests and removed before scenes are emitted or persisted; it adds no model
+request or public scene field.

package/starters/video-chat/package.json

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

package/starters/video-chat/server.ts

@@ -37,7 +37,7 @@ export const handleVideoChat = createVideoChatHandler({
     return text;
   },
   searchMedia: process.env.PEXELS_API_KEY
-    ? (query, { orientation, signal }) => findStockFootage(query, orientation, signal)
+    ? (query, { orientation, signal, scene }) => findStockFootage(query, orientation, signal, scene?.variables.stockSelection)
     : undefined,
   ...providers,
   welcome: {

package/starters/video-chat/stock.ts

@@ -9,11 +9,27 @@ interface PexelsVideo {
   url?: string;
   image?: string;
   title?: unknown;
+  description?: unknown;
   tags?: unknown;
   video_files?: { link?: string; width?: number; height?: number; file_type?: string }[];
 }
 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));
+function selectionHint(value: unknown) {
+  const phrase = (input: unknown) => {
+    if (typeof input !== 'string') return undefined;
+    const normalized = input.trim().toLowerCase().replace(/\s+/gu,' ').replaceAll('’', "'");
+    return normalized.length <= 48 && /^[\p{L}\p{N} '-]+$/u.test(normalized) && words(normalized).length <= 4 && terms(normalized).length ? normalized : undefined;
+  };
+  const raw = value && typeof value === 'object' ? value as Record<string, unknown> : {};
+  const subject = phrase(raw.subject);
+  if (!subject) return undefined;
+  const activity = phrase(raw.activity), equipment = phrase(raw.equipment);
+  const exclude = Array.isArray(raw.exclude) && raw.exclude.length <= 3 ? raw.exclude.map(phrase).filter((item): item is string => Boolean(item)) : [];
+  return {subject, ...(activity ? {activity} : {}), ...(equipment ? {equipment} : {}), ...(exclude.length ? {exclude} : {})};
+}
 function pexelsUrl(value: unknown): value is string {
   if (typeof value !== "string") return false;
   try {
@@ -27,11 +43,12 @@ function pexelsUrl(value: unknown): value is string {
  * Applications using this adapter must display a prominent link to Pexels.
  * https://www.pexels.com/api/documentation/#guidelines
  */
-export async function findStockFootage(query: string, orientation: VideoOrientation, signal: AbortSignal) {
+export async function findStockFootage(query: string, orientation: VideoOrientation, signal: AbortSignal, rawSelection?: unknown) {
   signal.throwIfAborted();
   const normalized = query.trim().toLowerCase().replace(/\s+/g, " ");
   const tokens = words(normalized);
-  const key = `${orientation}:${normalized}`;
+  const selection = selectionHint(rawSelection);
+  const key = JSON.stringify({version: 2, 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);
@@ -49,8 +66,14 @@ 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} ${tags}`).filter(token => !/^\d+$/.test(token));
-    const 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));
+    let matches = tokens.filter(token => subject.includes(token)).length;
+    if (selection && subject.length) {
+      const covers = (phrase: string) => terms(phrase).every(word => subject.includes(word));
+      if (!covers(selection.subject) || selection.exclude?.some(covers)) continue;
+      matches = 2 + Number(Boolean(selection.activity && covers(selection.activity)))
+        + Number(Boolean(selection.equipment && covers(selection.equipment)));
+    }
     // The documented Video resource can have only a numeric page URL and no
     // editorial metadata. Preserve provider search order for unknown relevance;
     // positive overlap ranks above it, while explicitly unrelated copy is skipped.