pellicule 0.0.2 → 0.0.4

package/bin/cli.js

@@ -5,6 +5,7 @@ import { resolve, extname, basename, dirname } from 'node:path'
 import { existsSync, readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { renderToMp4 } from '../src/render.js'
+import { extractVideoConfig, resolveVideoConfig } from '../src/macros/define-video-config.js'
 
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -50,35 +51,38 @@ ${c.bold('USAGE')}
 
 ${c.bold('OPTIONS')}
   ${c.info('-o, --output')} <file>     Output file path ${c.dim('(default: ./output.mp4)')}
-  ${c.info('-d, --duration')} <frames> Duration in frames ${c.dim('(default: 90)')}
-  ${c.info('-f, --fps')} <number>      Frames per second ${c.dim('(default: 30)')}
-  ${c.info('-w, --width')} <pixels>    Video width ${c.dim('(default: 1920)')}
-  ${c.info('-h, --height')} <pixels>   Video height ${c.dim('(default: 1080)')}
+  ${c.info('-d, --duration')} <frames> Duration in frames ${c.dim('(default: from component or 90)')}
+  ${c.info('-f, --fps')} <number>      Frames per second ${c.dim('(default: from component or 30)')}
+  ${c.info('-w, --width')} <pixels>    Video width ${c.dim('(default: from component or 1920)')}
+  ${c.info('-h, --height')} <pixels>   Video height ${c.dim('(default: from component or 1080)')}
   ${c.info('-r, --range')} <start:end> Frame range for partial render ${c.dim('(e.g., 100:200)')}
+  ${c.info('-a, --audio')} <file>     Audio file to include ${c.dim('(mp3, wav, aac, etc.)')}
   ${c.info('--help')}                 Show this help message
   ${c.info('--version')}               Show version number
 
+${c.bold('COMPONENT CONFIG')}
+  Use ${c.highlight('defineVideoConfig')} in your component to set defaults:
+
+  ${c.dim('defineVideoConfig({ durationInSeconds: 5 })')}
+
+  No import needed - it's a compiler macro like Vue's defineProps.
+  Then just run: ${c.highlight('pellicule')} ${c.dim('(no flags needed!)')}
+
 ${c.bold('EXAMPLES')}
-  ${c.dim('# Zero-config (renders Video.vue → output.mp4)')}
+  ${c.dim('# Zero-config (uses defineVideoConfig from component)')}
   ${c.highlight('pellicule')}
 
   ${c.dim('# Specify input file (.vue extension is optional)')}
   ${c.highlight('pellicule')} MyVideo
 
-  ${c.dim('# Custom output and duration')}
-  ${c.highlight('pellicule')} Video.vue -o intro.mp4 -d 150
+  ${c.dim('# Override component config with CLI flags')}
+  ${c.highlight('pellicule')} Video.vue -d 150
 
   ${c.dim('# 4K video at 60fps')}
   ${c.highlight('pellicule')} Video.vue -w 3840 -h 2160 -f 60
 
-  ${c.dim('# 10 second video')}
-  ${c.highlight('pellicule')} Video.vue -d 300 -f 30
-
   ${c.dim('# Render only frames 100-200 (for faster iteration)')}
-  ${c.highlight('pellicule')} Video.vue -d 300 -r 100:200
-
-  ${c.dim('# Render from frame 150 to 250')}
-  ${c.highlight('pellicule')} Video.vue -d 300 --range 150:250
+  ${c.highlight('pellicule')} Video.vue -r 100:200
 
 ${c.bold('DURATION HELPER')}
   frames = seconds * fps
@@ -120,6 +124,7 @@ async function main() {
       width: { type: 'string', short: 'w' },
       height: { type: 'string', short: 'h' },
       range: { type: 'string', short: 'r' },
+      audio: { type: 'string', short: 'a' },
       help: { type: 'boolean' },
       version: { type: 'boolean' }
     }
@@ -152,11 +157,34 @@ async function main() {
   if (!existsSync(inputPath)) fail(`File not found: ${input}`)
   if (extname(inputPath) !== '.vue') fail(`Input must be a .vue file, got: ${extname(inputPath) || '(no extension)'}`)
 
-  // Parse options with defaults
-  const fps = parseInt(values.fps || '30', 10)
-  const durationInFrames = parseInt(values.duration || '90', 10)
-  const width = parseInt(values.width || '1920', 10)
-  const height = parseInt(values.height || '1080', 10)
+  // Extract config from component (if defineVideoConfig is used)
+  const componentConfig = extractVideoConfig(inputPath)
+
+  // Resolve audio file path (CLI flag takes precedence over component config)
+  let audioPath = null
+  if (values.audio) {
+    audioPath = resolve(values.audio)
+    if (!existsSync(audioPath)) fail(`Audio file not found: ${values.audio}`)
+  } else if (componentConfig?.audio) {
+    // Resolve component audio path relative to the component file
+    audioPath = resolve(dirname(inputPath), componentConfig.audio)
+    if (!existsSync(audioPath)) fail(`Audio file not found: ${componentConfig.audio}`)
+  }
+
+  // Build CLI flags object (only include explicitly provided values)
+  const cliFlags = {}
+  if (values.duration !== undefined) cliFlags.duration = parseInt(values.duration, 10)
+  if (values.fps !== undefined) cliFlags.fps = parseInt(values.fps, 10)
+  if (values.width !== undefined) cliFlags.width = parseInt(values.width, 10)
+  if (values.height !== undefined) cliFlags.height = parseInt(values.height, 10)
+
+  // Resolve final config: defaults < componentConfig < cliFlags
+  const resolvedConfig = resolveVideoConfig({ componentConfig, cliFlags })
+
+  const fps = resolvedConfig.fps
+  const durationInFrames = resolvedConfig.durationInFrames
+  const width = resolvedConfig.width
+  const height = resolvedConfig.height
   const output = values.output || './output.mp4'
   const outputPath = resolve(output)
 
@@ -174,11 +202,11 @@ async function main() {
     if (isNaN(endFrame) || endFrame <= 0) fail(`Invalid end frame in range: ${endStr}`)
   }
 
-  // Validate options
-  if (isNaN(fps) || fps <= 0) fail(`Invalid fps value: ${values.fps}`)
-  if (isNaN(durationInFrames) || durationInFrames <= 0) fail(`Invalid duration value: ${values.duration}`)
-  if (isNaN(width) || width <= 0) fail(`Invalid width value: ${values.width}`)
-  if (isNaN(height) || height <= 0) fail(`Invalid height value: ${values.height}`)
+  // Validate resolved config
+  if (isNaN(fps) || fps <= 0) fail(`Invalid fps value: ${fps}`)
+  if (isNaN(durationInFrames) || durationInFrames <= 0) fail(`Invalid duration value: ${durationInFrames}`)
+  if (isNaN(width) || width <= 0) fail(`Invalid width value: ${width}`)
+  if (isNaN(height) || height <= 0) fail(`Invalid height value: ${height}`)
   if (startFrame >= endFrame) fail(`Start frame (${startFrame}) must be less than end frame (${endFrame})`)
   if (endFrame > durationInFrames) fail(`End frame (${endFrame}) exceeds duration (${durationInFrames})`)
 
@@ -191,12 +219,18 @@ async function main() {
   const partialSeconds = (framesToRender / fps).toFixed(1)
 
   console.log(`  ${c.bold('Input')}      ${c.info(basename(inputPath))}`)
+  if (componentConfig) {
+    console.log(`  ${c.bold('Config')}     ${c.highlight('defineVideoConfig')} ${c.dim('detected ✓')}`)
+  }
   console.log(`  ${c.bold('Output')}     ${c.info(basename(outputPath))}`)
   console.log(`  ${c.bold('Resolution')} ${width}x${height}`)
   console.log(`  ${c.bold('Duration')}   ${durationInFrames} frames @ ${fps}fps ${c.dim(`(${durationSeconds}s)`)}`)
   if (isPartialRender) {
     console.log(`  ${c.bold('Range')}      ${c.highlight(`frames ${startFrame}-${endFrame - 1}`)} ${c.dim(`(${framesToRender} frames, ${partialSeconds}s)`)}`)
   }
+  if (audioPath) {
+    console.log(`  ${c.bold('Audio')}      ${c.info(basename(audioPath))}`)
+  }
   console.log()
 
   const startTime = Date.now()
@@ -216,6 +250,7 @@ async function main() {
       width,
       height,
       output: outputPath,
+      audio: audioPath,
       silent: true,
       onProgress: ({ frame, total, fps: currentFps }) => {
         // Clear line and print progress (stays on same line)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pellicule",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Deterministic video rendering with Vue",
   "type": "module",
   "main": "./src/index.js",
@@ -27,9 +27,10 @@
     "url": "https://github.com/sailscastshq/pellicule"
   },
   "dependencies": {
-    "vite": "^5.0.0",
+    "@vue/compiler-sfc": "^3.0.0",
     "@vitejs/plugin-vue": "^5.0.0",
-    "playwright": "^1.40.0"
+    "playwright": "^1.40.0",
+    "vite": "^5.0.0"
   },
   "peerDependencies": {
     "vue": "^3.0.0"

package/src/bundler/vite.js

@@ -3,6 +3,7 @@ import vue from '@vitejs/plugin-vue'
 import { writeFile, mkdir, rm } from 'fs/promises'
 import { join, resolve, dirname, basename } from 'path'
 import { fileURLToPath } from 'url'
+import { pelliculeMacroPlugin } from '../macros/define-video-config.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const pelliculeSrc = resolve(__dirname, '..')
@@ -97,7 +98,7 @@ try {
   // Create Vite server rooted in the user's project directory
   const server = await createServer({
     root: tempDir,
-    plugins: [vue()],
+    plugins: [pelliculeMacroPlugin(), vue()],
     server: {
       port: 0,
       strictPort: false

package/src/macros/define-video-config.js

@@ -0,0 +1,146 @@
+/**
+ * defineVideoConfig - Compile-time macro for video configuration
+ *
+ * This module provides:
+ * 1. extractVideoConfig() - CLI uses this to read config from .vue files
+ * 2. pelliculeMacroPlugin() - Vite plugin that strips the macro from output
+ *
+ * Usage in components (no import needed):
+ *
+ *   defineVideoConfig({
+ *     durationInSeconds: 5
+ *   })
+ */
+
+import { parse } from '@vue/compiler-sfc'
+import { readFileSync } from 'fs'
+
+// ============================================================================
+// Config Extraction (for CLI)
+// ============================================================================
+
+/**
+ * Extract video config from a .vue file.
+ */
+export function extractVideoConfig(filePath) {
+  const source = readFileSync(filePath, 'utf-8')
+  return extractVideoConfigFromSource(source)
+}
+
+/**
+ * Extract video config from Vue SFC source code.
+ */
+export function extractVideoConfigFromSource(source) {
+  const { descriptor } = parse(source)
+  const scriptSetup = descriptor.scriptSetup
+
+  if (!scriptSetup) return null
+
+  const match = scriptSetup.content.match(/defineVideoConfig\s*\(\s*(\{[\s\S]*?\})\s*\)/)
+  if (!match) return null
+
+  try {
+    return parseObjectLiteral(match[1])
+  } catch (error) {
+    console.warn(`Failed to parse defineVideoConfig: ${error.message}`)
+    return null
+  }
+}
+
+/**
+ * Parse a static object literal string.
+ */
+function parseObjectLiteral(str) {
+  const trimmed = str.trim()
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) {
+    throw new Error('Not an object literal')
+  }
+
+  const config = {}
+  const regex = /(\w+)\s*:\s*(-?\d+(?:\.\d+)?|true|false|'[^']*'|"[^"]*")/g
+  let match
+
+  while ((match = regex.exec(trimmed)) !== null) {
+    const key = match[1]
+    let value = match[2]
+
+    if (value === 'true') value = true
+    else if (value === 'false') value = false
+    else if (value.startsWith("'") || value.startsWith('"')) value = value.slice(1, -1)
+    else value = parseFloat(value)
+
+    config[key] = value
+  }
+
+  return config
+}
+
+/**
+ * Resolve final config: defaults < defineVideoConfig < CLI flags
+ */
+export function resolveVideoConfig({ componentConfig, cliFlags }) {
+  const defaults = { fps: 30, width: 1920, height: 1080, durationInFrames: 90 }
+  const config = { ...defaults }
+
+  if (componentConfig) {
+    if (componentConfig.durationInSeconds !== undefined) {
+      const fps = componentConfig.fps || config.fps
+      config.durationInFrames = Math.round(componentConfig.durationInSeconds * fps)
+    }
+    if (componentConfig.durationInFrames !== undefined) config.durationInFrames = componentConfig.durationInFrames
+    if (componentConfig.fps !== undefined) config.fps = componentConfig.fps
+    if (componentConfig.width !== undefined) config.width = componentConfig.width
+    if (componentConfig.height !== undefined) config.height = componentConfig.height
+  }
+
+  if (cliFlags.duration !== undefined) config.durationInFrames = cliFlags.duration
+  if (cliFlags.fps !== undefined) config.fps = cliFlags.fps
+  if (cliFlags.width !== undefined) config.width = cliFlags.width
+  if (cliFlags.height !== undefined) config.height = cliFlags.height
+
+  return config
+}
+
+// ============================================================================
+// Vite Plugin (strips macro from compiled output)
+// ============================================================================
+
+/**
+ * Vite plugin that strips defineVideoConfig() calls.
+ * Runs before Vue's compiler (enforce: 'pre').
+ */
+export function pelliculeMacroPlugin() {
+  return {
+    name: 'pellicule:define-video-config',
+    enforce: 'pre',
+
+    transform(code, id) {
+      if (!id.endsWith('.vue') || !code.includes('defineVideoConfig')) {
+        return null
+      }
+
+      let transformed = code
+
+      // Remove import of defineVideoConfig (in case user mistakenly imports it)
+      transformed = transformed.replace(
+        /import\s*\{[^}]*defineVideoConfig[^}]*\}\s*from\s*['"]pellicule['"]\s*;?\n?/g,
+        (match) => {
+          const other = match
+            .replace(/defineVideoConfig\s*,?\s*/g, '')
+            .replace(/,\s*\}/g, '}')
+            .replace(/\{\s*,/g, '{')
+            .replace(/\{\s*\}/g, '')
+          return other.includes('{') && !other.match(/\{\s*\}/) ? other : ''
+        }
+      )
+
+      // Remove the defineVideoConfig() call
+      transformed = transformed.replace(
+        /defineVideoConfig\s*\(\s*\{[\s\S]*?\}\s*\)\s*;?\n?/g,
+        ''
+      )
+
+      return transformed !== code ? { code: transformed, map: null } : null
+    }
+  }
+}

package/src/renderer/encode.js

@@ -8,6 +8,7 @@ import path from 'path'
  * @param {string} options.framesDir - Directory containing frame-XXXXX.png files
  * @param {string} options.output - Output video path (default: './output.mp4')
  * @param {number} options.fps - Frames per second (default: 30)
+ * @param {string|null} options.audio - Audio file path to include (default: null)
  * @param {boolean} options.silent - Suppress console output (default: false)
  * @returns {Promise<string>} Path to the output video
  */
@@ -16,6 +17,7 @@ export function encodeVideo(options) {
     framesDir,
     output = './output.mp4',
     fps = 30,
+    audio = null,
     silent = false
   } = options
 
@@ -26,9 +28,11 @@ export function encodeVideo(options) {
       '-y', // Overwrite output
       '-framerate', String(fps),
       '-i', framePattern,
+      ...(audio ? ['-i', audio] : []),
       '-c:v', 'libx264',
       '-pix_fmt', 'yuv420p', // Compatibility
       '-preset', 'fast',
+      ...(audio ? ['-c:a', 'aac'] : []),
       output
     ]
 
@@ -72,24 +76,31 @@ export function encodeVideo(options) {
  * Full render pipeline: Vue component → frames → MP4
  *
  * @param {object} options - Same as renderVideo, plus output path
+ * @param {string|null} options.audio - Audio file path to include (default: null)
  * @param {boolean} options.silent - Suppress console output (default: false)
  * @returns {Promise<string>} Path to the output video
  */
 export async function renderToMp4(options) {
   const { renderVideo } = await import('./render.js')
 
-  const { output = './output.mp4', silent = false, ...renderOptions } = options
+  const { output = './output.mp4', audio = null, silent = false, ...renderOptions } = options
 
-  // Step 1: Render frames
-  const { framesDir } = await renderVideo({ ...renderOptions, silent })
+  // Step 1: Render frames (stored in .pellicule/frames)
+  const { framesDir, cleanup } = await renderVideo({ ...renderOptions, silent })
 
-  // Step 2: Encode to MP4
-  const videoPath = await encodeVideo({
-    framesDir,
-    output,
-    fps: renderOptions.fps || 30,
-    silent
-  })
+  try {
+    // Step 2: Encode to MP4
+    const videoPath = await encodeVideo({
+      framesDir,
+      output,
+      fps: renderOptions.fps || 30,
+      audio,
+      silent
+    })
 
-  return videoPath
+    return videoPath
+  } finally {
+    // Step 3: Cleanup .pellicule folder (removes frames automatically)
+    await cleanup()
+  }
 }

package/src/renderer/render.js

@@ -14,9 +14,8 @@ import { join } from 'path'
  * @param {number} options.endFrame - Last frame to render, exclusive (default: durationInFrames)
  * @param {number} options.width - Video width in pixels (default: 1920)
  * @param {number} options.height - Video height in pixels (default: 1080)
- * @param {string} options.outputDir - Directory for frame images (default: './frames')
  * @param {function} options.onProgress - Progress callback
- * @returns {Promise<{ framesDir: string, totalFrames: number }>}
+ * @returns {Promise<{ framesDir: string, totalFrames: number, cleanup: function }>}
  */
 export async function renderVideo(options) {
   const {
@@ -27,7 +26,6 @@ export async function renderVideo(options) {
     endFrame,
     width = 1920,
     height = 1080,
-    outputDir = './frames',
     onProgress,
     silent = false
   } = options
@@ -43,11 +41,12 @@ export async function renderVideo(options) {
   // Start Vite server with the video component
   log(`Starting Vite server for ${input}...`)
   const viteStart = Date.now()
-  const { url, cleanup } = await createVideoServer({ input, width, height })
+  const { url, cleanup, tempDir } = await createVideoServer({ input, width, height })
   log(`Server ready in ${Date.now() - viteStart}ms`)
 
-  // Ensure output directory exists
-  await mkdir(outputDir, { recursive: true })
+  // Store frames inside .pellicule (cleaned up automatically after encoding)
+  const framesDir = join(tempDir, 'frames')
+  await mkdir(framesDir, { recursive: true })
 
   // Launch browser
   const browser = await chromium.launch()
@@ -98,7 +97,7 @@ export async function renderVideo(options) {
 
       // Screenshot - output frames are numbered from 0
       const outputFrameNum = frame - startFrame
-      const framePath = join(outputDir, `frame-${String(outputFrameNum).padStart(5, '0')}.png`)
+      const framePath = join(framesDir, `frame-${String(outputFrameNum).padStart(5, '0')}.png`)
       await page.screenshot({ path: framePath })
 
       // Progress callback
@@ -124,11 +123,11 @@ export async function renderVideo(options) {
 
   } finally {
     await browser.close()
-    await cleanup()
+    // Don't cleanup here - frames are needed for encoding
+    // Cleanup will be called by renderToMp4 after encoding
   }
 
   log(`Total time: ${Date.now() - startTime}ms`)
-  log(`Frames saved to ${outputDir}`)
 
-  return { framesDir: outputDir, totalFrames: framesToRender }
+  return { framesDir, totalFrames: framesToRender, cleanup }
 }