studio-lumiere-cli 0.1.0

package/.agents/skills/generate-video/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: generate-video
+description: End-to-end guide to generate video with local-lumiere SDK/CLI; use for video generation workflows and parameter reference.
+---
+
+# Skill: Generate Video (local-lumiere)
+
+This document is a complete, end-to-end guide for an AI agent to generate video using the **local-lumiere** SDK/CLI. It is designed to be consumed as a standalone skill: read this file, then follow the steps exactly. It covers **every function**, **every parameter**, and **all configuration points** involved in video generation.
+
+---
+
+## Quick Start (60 seconds)
+
+1) Ensure `GEMINI_API_KEY` is set in your environment.
+2) Build the project:
+
+```
+npm install
+npm run build
+```
+
+3) Generate a video via CLI:
+
+```
+node dist/cli.js video \
+  --prompt "A cinematic close-up of a model gently turning her head, earrings catching soft light." \
+  --aspect 9:16 \
+  --duration 5
+```
+
+4) Find output files under `outputs/videos/<timestamp>/`.
+
+---
+
+## 0) Purpose
+
+The goal is to generate short, high-end jewelry videos locally using Gemini/Veo via the SDK. This skill focuses on **video generation** only. It does not cover image generation, refinement, upscaling, or Muse creation (except for references in prompt crafting).
+
+---
+
+## 1) Where the Video Generation API Lives
+
+**SDK entrypoint**: `src/index.ts`
+
+- `generateVideo` (primary API)
+
+**Pipeline implementation**: `src/pipelines/generateVideo.ts`
+
+**Gemini client wrapper**: `src/clients/geminiClient.ts`
+
+**File I/O**: `src/storage/files.ts`
+
+---
+
+## 2) Required Environment and Configuration
+
+### 2.1 Environment Variables
+
+- `GEMINI_API_KEY` (required)
+  - Used by `GeminiClient` to authenticate to Gemini APIs.
+
+- `LUMIERE_OUTPUT_DIR` (optional)
+  - Default output directory for all generated assets.
+  - Defaults to `outputs` if not set.
+
+### 2.2 Runtime Config Object
+
+All SDK functions expect a `LumiereConfig` object:
+
+```ts
+export interface LumiereConfig {
+  apiKey: string;        // required
+  outputDir: string;     // required (can be read from env)
+  models?: {
+    prompt?: string;     // Gemini text model
+    image?: string;      // Gemini image model
+    video?: string;      // Gemini video model
+  };
+  retry?: {
+    maxRetries?: number; // default: 3
+    baseDelayMs?: number;// default: 1500
+    maxDelayMs?: number; // default: 12000
+  };
+}
+```
+
+Defaults if omitted:
+
+- `models.prompt`: `gemini-3-flash-preview`
+- `models.image`: `gemini-3-flash-preview-image`
+- `models.video`: `veo-3.1-generate-preview`
+- `retry.maxRetries`: 3
+- `retry.baseDelayMs`: 1500
+- `retry.maxDelayMs`: 12000
+
+### 2.3 Output Directory Structure
+
+`generateVideo()` creates a timestamped folder under `outputDir`:
+
+```
+outputs/
+  videos/
+    2026-02-11T19-40-12-123Z/
+      video.mp4
+      video.json
+```
+
+The timestamp is generated in `resolveOutputDir()` in `src/storage/files.ts`.
+
+---
+
+## 3) Primary Function: generateVideo
+
+### 3.1 Function Signature
+
+```ts
+export const generateVideo = async (
+  config: LumiereConfig,
+  request: VideoRequest
+): Promise<VideoResult>
+```
+
+### 3.2 Request Object: VideoRequest
+
+```ts
+export interface VideoRequest {
+  prompt: string;              // Required. Full video prompt.
+  imageInput?: string;         // Optional. Reserved for future use (not currently used).
+  durationSeconds?: number;    // Optional. Duration in seconds.
+  aspectRatio?: AspectRatio;   // Optional. "1:1" | "3:4" | "4:3" | "9:16" | "16:9"
+  outputDir?: string;          // Optional. Override config.outputDir.
+}
+```
+
+### 3.3 Response Object: VideoResult
+
+```ts
+export interface VideoResult {
+  operationName?: string; // Operation name from Gemini/Veo
+  videoPath?: string;     // Path to saved .mp4 if available
+  logPath: string;        // Path to video.json log
+}
+```
+
+---
+
+## 4) Gemini Video Generation Call
+
+Video generation is performed by:
+
+```ts
+GeminiClient.generateVideo({
+  prompt,
+  aspectRatio,
+  durationSeconds
+})
+```
+
+### 4.1 Prompt
+
+The prompt should be **complete and explicit** about:
+
+- Subject (model/jewelry)
+- Motion and camera movement
+- Lighting and mood
+- Composition and framing
+
+Example:
+
+"A cinematic close-up of a model gently turning her head, earrings catching soft light. High-end jewelry commercial aesthetic. Slow, elegant motion. Shallow depth of field."
+
+### 4.2 Aspect Ratio
+
+Optional. Must be one of:
+
+- `1:1`
+- `3:4`
+- `4:3`
+- `9:16`
+- `16:9`
+
+### 4.3 Duration
+
+Optional. Duration in seconds (integer). If omitted, the provider default is used.
+
+### 4.4 Long-Running Operation
+
+`GeminiClient.generateVideo()` polls the operation until completion:
+
+- Starts with `ai.models.generateVideos()`
+- Polls using `ai.operations.getVideosOperation()`
+- Returns `operationName` and `videoBytes` if available
+
+---
+
+## 5) Output Saving and Logging
+
+When the operation completes and video bytes are available:
+
+- The file is saved as `video.mp4` in the output folder
+- A JSON log is written as `video.json`
+
+Example log:
+
+```json
+{
+  "prompt": "A cinematic close-up...",
+  "aspectRatio": "9:16",
+  "durationSeconds": 5,
+  "operationName": "operations/abc123",
+  "videoPath": "outputs/videos/2026-02-11.../video.mp4"
+}
+```
+
+If no video bytes are returned, `videoPath` will be omitted but the log still records `operationName`.
+
+---
+
+## 6) CLI Usage (Full Parameters)
+
+The CLI is implemented in `src/cli.ts` and compiled to `dist/cli.js`.
+
+### 6.1 Video Command
+
+```
+node dist/cli.js video \
+  --prompt "Cinematic head turn showing earrings" \
+  --aspect 9:16 \
+  --duration 5
+```
+
+### 6.2 CLI Flags
+
+- `--prompt`: **required**
+- `--aspect`: optional (aspect ratio string)
+- `--duration`: optional (seconds)
+
+---
+
+## 7) Function Call Example (SDK)
+
+```ts
+import { generateVideo } from "./dist/index.js";
+
+const result = await generateVideo(
+  {
+    apiKey: process.env.GEMINI_API_KEY!,
+    outputDir: "outputs",
+    models: {
+      video: "veo-3.1-generate-preview"
+    },
+    retry: {
+      maxRetries: 3,
+      baseDelayMs: 1500,
+      maxDelayMs: 12000
+    }
+  },
+  {
+    prompt: "A cinematic close-up of a model gently turning her head, earrings catching soft light.",
+    aspectRatio: "9:16",
+    durationSeconds: 5
+  }
+);
+
+console.log(result);
+```
+
+---
+
+## 8) Error Handling and Retries
+
+All Gemini calls use a retry wrapper:
+
+```ts
+retry: {
+  maxRetries: 3,
+  baseDelayMs: 1500,
+  maxDelayMs: 12000
+}
+```
+
+Retryable error detection looks for:
+- HTTP 429 / 503
+- “overloaded”, “unavailable”, “timeout” text
+
+If all retries fail, the error is thrown as-is.
+
+---
+
+## 9) Extending or Modifying the Skill
+
+If you want a different video model or output duration defaults:
+
+- Override `config.models.video` when calling `generateVideo`.
+- Modify `src/clients/geminiClient.ts` for custom polling intervals or defaults.
+- Update the CLI to expose additional parameters.
+
+---
+
+## 10) Quick Checklist for an AI Agent
+
+1) Ensure `GEMINI_API_KEY` is set.
+2) Write a clear, cinematic prompt (subject, motion, lighting, mood).
+3) Decide aspect ratio and duration.
+4) Call `generateVideo(config, request)` or use the CLI.
+5) Read output paths and logs from the result.
+
+---
+
+## 11) Related Files (For Reference)
+
+- `src/pipelines/generateVideo.ts`
+- `src/clients/geminiClient.ts`
+- `src/storage/files.ts`
+- `src/cli.ts`
+
+End of skill.
+
+## Related Skills
+
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\generate-images.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\generate-video.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\refine-images.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\muse-management.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\tired-girl.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\image-grid.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\config-troubleshooting.md`
+

package/.agents/skills/image-grid/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: image-grid
+description: Assemble multiple images into a grid using the local-lumiere SDK/CLI; use when you need tiled or collage layouts.
+---
+
+# Skill: Image Grid Assembly (local-lumiere)
+
+This document explains how to assemble multiple images into a grid using the **local-lumiere** SDK/CLI.
+
+---
+
+## Quick Start (60 seconds)
+
+```
+node dist/cli.js grid \
+  --inputs "C:\\path\\to\\img1.png,C:\\path\\to\\img2.png,C:\\path\\to\\img3.png,C:\\path\\to\\img4.png" \
+  --output "C:\\path\\to\\grid.png" \
+  --columns 2 --rows 2 --background "#000000" --padding 20
+```
+
+---
+
+## 1) API Location
+
+- Helper: `src/image/grid.ts`
+- Export: `createImageGrid`
+- CLI: `grid`
+
+---
+
+## 2) Function Signature
+
+```ts
+export const createImageGrid = async (
+  inputPaths: string[],
+  outputPath: string,
+  options: GridOptions
+): Promise<void>
+```
+
+### GridOptions
+
+```ts
+export interface GridOptions {
+  columns: number;
+  rows: number;
+  padding?: number;   // default 20
+  background?: string;// default #000000
+  tileWidth?: number; // optional fixed tile size
+  tileHeight?: number;// optional fixed tile size
+}
+```
+
+---
+
+## 3) Behavior
+
+- Creates a blank canvas sized to fit all tiles + padding.
+- Resizes each image to the tile size with `fit: contain` (keeps aspect ratio).
+- Composites images into row/column slots.
+- Unused slots are left as background.
+
+---
+
+## 4) CLI Usage
+
+```
+node dist/cli.js grid --inputs "img1.png,img2.png,img3.png,img4.png" --output "grid.png" --columns 2 --rows 2 --background "#000000" --padding 20
+```
+
+---
+
+## 5) SDK Example
+
+```ts
+import { createImageGrid } from "./dist/index.js";
+
+await createImageGrid(
+  ["img1.png", "img2.png", "img3.png", "img4.png"],
+  "grid.png",
+  { columns: 2, rows: 2, padding: 20, background: "#000000" }
+);
+```
+
+---
+
+## Related Skills
+
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\generate-images.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\generate-video.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\refine-images.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\muse-management.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\tired-girl.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\image-grid.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\config-troubleshooting.md`
+

package/.agents/skills/image-overlay/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: image-overlay
+description: Overlay one image (logo, watermark, sticker) onto another at a chosen size and position. Use when asked to slap/paste a logo on top of an image, add a watermark, composite two images, or place an image at specific coordinates.
+---
+
+# Image Overlay
+
+## Quick Start
+
+```bash
+node .agents/skills/image-overlay/scripts/overlay-image.js \
+  --base path/to/base.jpg \
+  --overlay path/to/logo.png \
+  --output path/to/output.png \
+  --scale 0.2 \
+  --position bottom-right \
+  --margin 24
+```
+
+## Inputs
+
+- `--base`: path to the background image.
+- `--overlay`: path to the image/logo to place on top.
+- `--output`: path for the final composited image.
+
+## Sizing
+
+- Use `--scale` to size the overlay relative to base width. Default is `0.2` if no size is provided.
+- Use `--width` and/or `--height` for explicit pixel sizing.
+- If both `--width` and `--height` are provided, the overlay is resized with `contain` to preserve aspect ratio.
+
+Example (explicit width):
+
+```bash
+node .agents/skills/image-overlay/scripts/overlay-image.js \
+  --base input.jpg \
+  --overlay logo.png \
+  --output output.png \
+  --width 320 \
+  --position top-right
+```
+
+## Positioning
+
+- Use `--position` with one of: `top-left`, `top-center`, `top-right`, `center`, `bottom-left`, `bottom-center`, `bottom-right`.
+- Use `--margin` to offset from edges (default `24`).
+- Use `--offset-x` and `--offset-y` to nudge the overlay relative to the chosen position.
+- Use `--x` and `--y` to place the overlay at absolute coordinates (overrides `--position`).
+- Use `--opacity` between `0` and `1` to make the overlay more subtle (e.g., `0.75`).
+
+Example (absolute coordinates):
+
+```bash
+node .agents/skills/image-overlay/scripts/overlay-image.js \
+  --base input.jpg \
+  --overlay logo.png \
+  --output output.png \
+  --scale 0.15 \
+  --x 120 \
+  --y 80
+```
+
+## Script
+
+- `scripts/overlay-image.js` performs the composite using Sharp.
+- The script auto-rotates images via EXIF orientation and clamps the overlay within the base image bounds.

package/.agents/skills/image-overlay/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Image Overlay"
+  short_description: "Overlay a logo onto another image."
+  default_prompt: "Overlay one image onto another at a specified size and position using the script in this skill."

package/.agents/skills/image-overlay/scripts/overlay-image.js

@@ -0,0 +1,218 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import sharp from "sharp";
+
+const USAGE = `
+Overlay one image onto another.
+
+Usage:
+  node .agents/skills/image-overlay/scripts/overlay-image.js \
+    --base path/to/base.jpg \
+    --overlay path/to/logo.png \
+    --output path/to/output.png \
+    [--scale 0.2] [--width 320] [--height 200] \
+    [--position bottom-right] [--margin 24] \
+    [--offset-x 0] [--offset-y 0] \
+    [--x 120] [--y 80] \
+    [--opacity 0.75]
+
+Notes:
+  - Provide either --scale or --width/--height.
+  - If none are provided, default scale is 0.2 (20% of base width).
+  - If --x/--y are provided, they override --position.
+`;
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    i += 1;
+  }
+  return args;
+}
+
+function toNumber(value, label) {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Invalid ${label}: ${value}`);
+  }
+  return parsed;
+}
+
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+if (args.help) {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+const basePath = args.base;
+const overlayPath = args.overlay;
+const outputPath = args.output;
+
+if (!basePath || !overlayPath || !outputPath) {
+  console.error("Missing required arguments: --base, --overlay, --output");
+  console.log(USAGE);
+  process.exit(1);
+}
+
+const scaleArg = toNumber(args.scale, "scale");
+const opacityArg = toNumber(args.opacity, "opacity");
+const widthArg = toNumber(args.width, "width");
+const heightArg = toNumber(args.height, "height");
+
+let scale = scaleArg;
+if (scale === undefined && widthArg === undefined && heightArg === undefined) {
+  scale = 0.2;
+}
+
+if (scale !== undefined && scale <= 0) {
+  throw new Error("Scale must be greater than 0.");
+}
+if (widthArg !== undefined && widthArg <= 0) {
+  throw new Error("Width must be greater than 0.");
+}
+if (heightArg !== undefined && heightArg <= 0) {
+  throw new Error("Height must be greater than 0.");
+}
+if (opacityArg !== undefined && (opacityArg < 0 || opacityArg > 1)) {
+  throw new Error("Opacity must be between 0 and 1.");
+}
+
+const baseImage = sharp(basePath).rotate();
+const baseMeta = await baseImage.metadata();
+
+if (!baseMeta.width || !baseMeta.height) {
+  throw new Error("Unable to read base image dimensions.");
+}
+
+const resizeOptions = {};
+if (scale !== undefined) {
+  resizeOptions.width = Math.max(1, Math.round(baseMeta.width * scale));
+} else {
+  if (widthArg !== undefined) resizeOptions.width = Math.round(widthArg);
+  if (heightArg !== undefined) resizeOptions.height = Math.round(heightArg);
+}
+if (resizeOptions.width || resizeOptions.height) {
+  resizeOptions.fit = "contain";
+}
+
+let overlaySharp = sharp(overlayPath).rotate();
+if (resizeOptions.width || resizeOptions.height) {
+  overlaySharp = overlaySharp.resize(resizeOptions);
+}
+let overlayBuffer;
+let overlayWidth;
+let overlayHeight;
+
+if (opacityArg !== undefined && opacityArg < 1) {
+  const { data, info } = await overlaySharp
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  for (let i = 3; i < data.length; i += 4) {
+    data[i] = Math.round(data[i] * opacityArg);
+  }
+
+  overlayWidth = info.width;
+  overlayHeight = info.height;
+  overlayBuffer = await sharp(data, {
+    raw: {
+      width: info.width,
+      height: info.height,
+      channels: 4
+    }
+  })
+    .png()
+    .toBuffer();
+} else {
+  const { data, info } = await overlaySharp.png().toBuffer({ resolveWithObject: true });
+  overlayWidth = info.width;
+  overlayHeight = info.height;
+  overlayBuffer = data;
+}
+
+if (!overlayWidth || !overlayHeight) {
+  throw new Error("Unable to read overlay image dimensions.");
+}
+
+const margin = Math.round(toNumber(args.margin, "margin") ?? 24);
+const offsetX = Math.round(toNumber(args["offset-x"], "offset-x") ?? 0);
+const offsetY = Math.round(toNumber(args["offset-y"], "offset-y") ?? 0);
+
+let left;
+let top;
+
+const xArg = toNumber(args.x, "x");
+const yArg = toNumber(args.y, "y");
+
+if (xArg !== undefined || yArg !== undefined) {
+  left = Math.round(xArg ?? margin);
+  top = Math.round(yArg ?? margin);
+} else {
+  const position = String(args.position ?? "bottom-right").toLowerCase();
+  switch (position) {
+    case "top-left":
+      left = margin;
+      top = margin;
+      break;
+    case "top-center":
+      left = (baseMeta.width - overlayWidth) / 2;
+      top = margin;
+      break;
+    case "top-right":
+      left = baseMeta.width - overlayWidth - margin;
+      top = margin;
+      break;
+    case "center":
+      left = (baseMeta.width - overlayWidth) / 2;
+      top = (baseMeta.height - overlayHeight) / 2;
+      break;
+    case "bottom-left":
+      left = margin;
+      top = baseMeta.height - overlayHeight - margin;
+      break;
+    case "bottom-center":
+      left = (baseMeta.width - overlayWidth) / 2;
+      top = baseMeta.height - overlayHeight - margin;
+      break;
+    case "bottom-right":
+    default:
+      left = baseMeta.width - overlayWidth - margin;
+      top = baseMeta.height - overlayHeight - margin;
+      break;
+  }
+}
+
+left = clamp(Math.round(left + offsetX), 0, Math.max(0, baseMeta.width - overlayWidth));
+top = clamp(Math.round(top + offsetY), 0, Math.max(0, baseMeta.height - overlayHeight));
+
+await fs.mkdir(path.dirname(outputPath), { recursive: true });
+
+await baseImage
+  .composite([
+    {
+      input: overlayBuffer,
+      left,
+      top
+    }
+  ])
+  .toFile(outputPath);
+
+console.log(`Overlay complete: ${outputPath}`);
+console.log(`Overlay size: ${overlayWidth}x${overlayHeight}`);
+console.log(`Position: left=${left}, top=${top}`);