pellicule 0.0.1 → 0.0.2

package/bin/cli.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util'
+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'
+
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf-8'))
+const VERSION = pkg.version
+
+// ANSI color codes (no dependencies needed)
+const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  pellicule: '\x1b[38;2;66;184;131m', // #42b883 - Vue green
+  bgPellicule: '\x1b[48;2;66;184;131m'
+}
+
+const c = {
+  error: (s) => `${colors.red}${s}${colors.reset}`,
+  warn: (s) => `${colors.yellow}${s}${colors.reset}`,
+  info: (s) => `${colors.cyan}${s}${colors.reset}`,
+  dim: (s) => `${colors.dim}${s}${colors.reset}`,
+  bold: (s) => `${colors.bold}${s}${colors.reset}`,
+  highlight: (s) => `${colors.pellicule}${s}${colors.reset}`,
+  brand: (s) => `${colors.bgPellicule}${colors.white}${colors.bold}${s}${colors.reset}`
+}
+
+function fail(msg, hint) {
+  console.error(c.error(`\nError: ${msg}\n`))
+  if (hint) console.error(c.dim(`  ${hint}\n`))
+  process.exit(1)
+}
+
+const HELP = `
+${c.bold('pellicule')} ${c.dim(`v${VERSION}`)} - Render Vue components to video
+
+${c.bold('USAGE')}
+  ${c.highlight('pellicule')}                            ${c.dim('→ renders Video.vue to output.mp4')}
+  ${c.highlight('pellicule')} <input.vue>                ${c.dim('→ custom input file')}
+  ${c.highlight('pellicule')} <input.vue> -o <file>      ${c.dim('→ custom output path')}
+
+${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('-r, --range')} <start:end> Frame range for partial render ${c.dim('(e.g., 100:200)')}
+  ${c.info('--help')}                 Show this help message
+  ${c.info('--version')}               Show version number
+
+${c.bold('EXAMPLES')}
+  ${c.dim('# Zero-config (renders Video.vue → output.mp4)')}
+  ${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('# 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.bold('DURATION HELPER')}
+  frames = seconds * fps
+  ${c.dim('3 seconds at 30fps  = 90 frames')}
+  ${c.dim('5 seconds at 30fps  = 150 frames')}
+  ${c.dim('10 seconds at 60fps = 600 frames')}
+
+${c.dim('Documentation: https://docs.sailscasts.com/pellicule')}
+`
+
+function printBanner() {
+  console.log()
+  console.log(`  ${c.brand(' PELLICULE ')} ${c.dim(`v${VERSION}`)}`)
+  console.log()
+}
+
+function formatTime(ms) {
+  if (ms < 1000) return `${ms}ms`
+  const seconds = (ms / 1000).toFixed(1)
+  return `${seconds}s`
+}
+
+function formatProgress(frame, total, fps) {
+  const percent = Math.round(((frame + 1) / total) * 100)
+  const barWidth = 30
+  const filled = Math.round((percent / 100) * barWidth)
+  const empty = barWidth - filled
+  const bar = c.highlight('█'.repeat(filled)) + c.dim('░'.repeat(empty))
+  return `  ${bar} ${c.bold(percent + '%')} ${c.dim(`(${frame + 1}/${total} @ ${fps.toFixed(1)} fps)`)}`
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      output: { type: 'string', short: 'o' },
+      duration: { type: 'string', short: 'd' },
+      fps: { type: 'string', short: 'f' },
+      width: { type: 'string', short: 'w' },
+      height: { type: 'string', short: 'h' },
+      range: { type: 'string', short: 'r' },
+      help: { type: 'boolean' },
+      version: { type: 'boolean' }
+    }
+  })
+
+  // Handle help and version
+  if (values.help) {
+    console.log(HELP)
+    process.exit(0)
+  }
+
+  if (values.version) {
+    console.log(VERSION)
+    process.exit(0)
+  }
+
+  // Default to Video.vue if no input provided
+  const input = positionals[0] || 'Video.vue'
+
+  // Try to resolve the input file, auto-appending .vue if needed
+  let inputPath = resolve(input)
+
+  if (!existsSync(inputPath) && !input.endsWith('.vue')) {
+    const withVue = resolve(input + '.vue')
+    if (existsSync(withVue)) {
+      inputPath = withVue
+    }
+  }
+
+  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)
+  const output = values.output || './output.mp4'
+  const outputPath = resolve(output)
+
+  // Parse optional range (start:end format)
+  let startFrame = 0
+  let endFrame = durationInFrames
+
+  if (values.range) {
+    const rangeParts = values.range.split(':')
+    if (rangeParts.length !== 2) fail(`Invalid range format: ${values.range}`, 'Expected format: start:end (e.g., 100:200)')
+    const [startStr, endStr] = rangeParts
+    startFrame = parseInt(startStr, 10)
+    endFrame = parseInt(endStr, 10)
+    if (isNaN(startFrame) || startFrame < 0) fail(`Invalid start frame in range: ${startStr}`)
+    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}`)
+  if (startFrame >= endFrame) fail(`Start frame (${startFrame}) must be less than end frame (${endFrame})`)
+  if (endFrame > durationInFrames) fail(`End frame (${endFrame}) exceeds duration (${durationInFrames})`)
+
+  // Print banner and config
+  printBanner()
+
+  const isPartialRender = startFrame > 0 || endFrame < durationInFrames
+  const framesToRender = endFrame - startFrame
+  const durationSeconds = (durationInFrames / fps).toFixed(1)
+  const partialSeconds = (framesToRender / fps).toFixed(1)
+
+  console.log(`  ${c.bold('Input')}      ${c.info(basename(inputPath))}`)
+  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)`)}`)
+  }
+  console.log()
+
+  const startTime = Date.now()
+
+  // ANSI escape codes for line control
+  const clearLine = '\x1b[2K'  // Clear entire line
+  const cursorToStart = '\r'   // Move cursor to start of line
+
+  try {
+    // Render with progress callback
+    await renderToMp4({
+      input: inputPath,
+      fps,
+      durationInFrames,
+      startFrame,
+      endFrame,
+      width,
+      height,
+      output: outputPath,
+      silent: true,
+      onProgress: ({ frame, total, fps: currentFps }) => {
+        // Clear line and print progress (stays on same line)
+        process.stdout.write(clearLine + cursorToStart + formatProgress(frame, total, currentFps || fps))
+      }
+    })
+
+    // Clear progress line when done
+    process.stdout.write(clearLine + cursorToStart)
+
+    const totalTime = Date.now() - startTime
+    console.log()
+    console.log(`  ${c.highlight('Done!')} Rendered ${framesToRender} frames in ${formatTime(totalTime)}`)
+    console.log(`  ${c.dim('Output:')} ${outputPath}`)
+    console.log()
+
+  } catch (error) {
+    // Clear progress line on error
+    process.stdout.write(clearLine + cursorToStart)
+    console.error()
+    console.error(c.error(`  Error: ${error.message}`))
+    console.error()
+
+    if (error.message.includes('ffmpeg')) {
+      console.error(c.warn('  Hint: Make sure FFmpeg is installed and available in your PATH'))
+      console.error(c.dim('  Install: https://ffmpeg.org/download.html'))
+      console.error()
+    }
+
+    process.exit(1)
+  }
+}
+
+main().catch((error) => {
+  console.error(c.error(`\nUnexpected error: ${error.message}\n`))
+  process.exit(1)
+})

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "pellicule",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Deterministic video rendering with Vue",
   "type": "module",
   "main": "./src/index.js",
+  "bin": {
+    "pellicule": "./bin/cli.js"
+  },
   "exports": {
     ".": "./src/index.js",
     "./render": "./src/render.js"

package/src/components/Sequence.vue

@@ -0,0 +1,34 @@
+<script setup>
+import { computed } from 'vue'
+import { useFrame } from '../composables/frame.js'
+import { provideSequence } from '../composables/sequence.js'
+
+const props = defineProps({
+  /**
+   * The frame number where this sequence starts
+   */
+  from: {
+    type: Number,
+    required: true
+  },
+  /**
+   * Duration of this sequence in frames
+   */
+  durationInFrames: {
+    type: Number,
+    required: true
+  }
+})
+
+const globalFrame = useFrame()
+
+// Provide sequence context to children
+const { isActive } = provideSequence(props.from, props.durationInFrames)
+
+// Compute whether to show content
+const shouldRender = computed(() => isActive.value)
+</script>
+
+<template>
+  <slot v-if="shouldRender" />
+</template>

package/src/composables/frame.js

@@ -0,0 +1,24 @@
+import { inject, computed } from 'vue'
+import { FRAME_KEY } from './keys.js'
+
+/**
+ * Get the current frame number.
+ * Must be used within a Pellicule render context.
+ *
+ * @returns {import('vue').ComputedRef<number>} Current frame number
+ *
+ * @example
+ * const frame = useFrame()
+ * const opacity = computed(() => frame.value / 30) // fade in over 1 second at 30fps
+ */
+export function useFrame() {
+  const frame = inject(FRAME_KEY)
+
+  if (frame === undefined) {
+    throw new Error(
+      'useFrame() must be used within a Pellicule render context'
+    )
+  }
+
+  return computed(() => frame.value)
+}

package/src/composables/keys.js

@@ -0,0 +1,7 @@
+/**
+ * Injection keys for Pellicule context
+ * Using Symbol.for() so keys are shared across module instances
+ */
+export const FRAME_KEY = Symbol.for('pellicule-frame')
+export const CONFIG_KEY = Symbol.for('pellicule-config')
+export const SEQUENCE_KEY = Symbol.for('pellicule-sequence')

package/src/composables/sequence.js

@@ -0,0 +1,82 @@
+import { inject, computed, provide } from 'vue'
+import { SEQUENCE_KEY } from './keys.js'
+import { useFrame } from './frame.js'
+
+/**
+ * Get sequence timing information.
+ * Can be used in two ways:
+ *
+ * 1. Inside a <Sequence> component - returns timing for that sequence
+ * 2. With explicit timing - useSequence(from, durationInFrames)
+ *
+ * @param {number} [from] - Start frame (optional if inside <Sequence>)
+ * @param {number} [durationInFrames] - Duration in frames (optional if inside <Sequence>)
+ * @returns {{ localFrame: ComputedRef<number>, progress: ComputedRef<number>, isActive: ComputedRef<boolean> }}
+ *
+ * @example
+ * // Inside a <Sequence> component
+ * const { localFrame, progress, isActive } = useSequence()
+ *
+ * @example
+ * // With explicit timing
+ * const verse1 = useSequence(0, 90)
+ * const verse2 = useSequence(90, 90)
+ */
+export function useSequence(from, durationInFrames) {
+  const globalFrame = useFrame()
+
+  // If arguments provided, use them directly
+  if (from !== undefined && durationInFrames !== undefined) {
+    const end = from + durationInFrames
+
+    const localFrame = computed(() => Math.max(0, globalFrame.value - from))
+    const progress = computed(() => {
+      if (globalFrame.value < from) return 0
+      if (globalFrame.value >= end) return 1
+      return (globalFrame.value - from) / durationInFrames
+    })
+    const isActive = computed(() =>
+      globalFrame.value >= from && globalFrame.value < end
+    )
+
+    return { localFrame, progress, isActive }
+  }
+
+  // Otherwise, try to get from parent <Sequence>
+  const sequenceContext = inject(SEQUENCE_KEY, null)
+
+  if (!sequenceContext) {
+    throw new Error(
+      'useSequence() must be used within a <Sequence> component or called with (from, durationInFrames) arguments'
+    )
+  }
+
+  return sequenceContext
+}
+
+/**
+ * Provide sequence context to children.
+ * Used internally by the <Sequence> component.
+ *
+ * @param {number} from - Start frame
+ * @param {number} durationInFrames - Duration in frames
+ */
+export function provideSequence(from, durationInFrames) {
+  const globalFrame = useFrame()
+  const end = from + durationInFrames
+
+  const localFrame = computed(() => Math.max(0, globalFrame.value - from))
+  const progress = computed(() => {
+    if (globalFrame.value < from) return 0
+    if (globalFrame.value >= end) return 1
+    return (globalFrame.value - from) / durationInFrames
+  })
+  const isActive = computed(() =>
+    globalFrame.value >= from && globalFrame.value < end
+  )
+
+  const context = { localFrame, progress, isActive, from, durationInFrames }
+  provide(SEQUENCE_KEY, context)
+
+  return context
+}

package/src/composables/video-config.js

@@ -0,0 +1,23 @@
+import { inject } from 'vue'
+import { CONFIG_KEY } from './keys.js'
+
+/**
+ * Get the video configuration (fps, duration, dimensions).
+ * Must be used within a Pellicule render context.
+ *
+ * @returns {{ fps: number, durationInFrames: number, width: number, height: number }}
+ *
+ * @example
+ * const { fps, durationInFrames, width, height } = useVideoConfig()
+ */
+export function useVideoConfig() {
+  const config = inject(CONFIG_KEY)
+
+  if (!config) {
+    throw new Error(
+      'useVideoConfig() must be used within a Pellicule render context'
+    )
+  }
+
+  return config
+}

package/src/index.js

@@ -6,7 +6,13 @@
  */
 
 // Composables
-export { useFrame, useVideoConfig, FRAME_KEY, CONFIG_KEY } from './composables.js'
+export { useFrame } from './composables/frame.js'
+export { useVideoConfig } from './composables/video-config.js'
+export { useSequence } from './composables/sequence.js'
+export { FRAME_KEY, CONFIG_KEY, SEQUENCE_KEY } from './composables/keys.js'
+
+// Components
+export { default as Sequence } from './components/Sequence.vue'
 
 // Animation utilities
-export { interpolate, sequence, Easing } from './math.js'
+export { interpolate, sequence, Easing } from './utils/math.js'

package/src/renderer/render.js

@@ -9,7 +9,9 @@ import { join } from 'path'
  * @param {object} options
  * @param {string} options.input - Path to the .vue file
  * @param {number} options.fps - Frames per second (default: 30)
- * @param {number} options.durationInFrames - Total frames to render
+ * @param {number} options.durationInFrames - Total frames in the video (for animation calculations)
+ * @param {number} options.startFrame - First frame to render (default: 0)
+ * @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')
@@ -21,6 +23,8 @@ export async function renderVideo(options) {
     input,
     fps = 30,
     durationInFrames,
+    startFrame = 0,
+    endFrame,
     width = 1920,
     height = 1080,
     outputDir = './frames',
@@ -28,6 +32,10 @@ export async function renderVideo(options) {
     silent = false
   } = options
 
+  // Calculate actual frame range to render
+  const actualEndFrame = endFrame !== undefined ? endFrame : durationInFrames
+  const framesToRender = actualEndFrame - startFrame
+
   const log = silent ? () => {} : console.log.bind(console)
 
   const startTime = Date.now()
@@ -62,10 +70,13 @@ export async function renderVideo(options) {
     }
   })
 
-  log(`Rendering ${durationInFrames} frames at ${fps}fps (${width}x${height})`)
+  const rangeInfo = startFrame > 0 || actualEndFrame < durationInFrames
+    ? ` (frames ${startFrame}-${actualEndFrame - 1})`
+    : ''
+  log(`Rendering ${framesToRender} frames at ${fps}fps (${width}x${height})${rangeInfo}`)
 
   try {
-    // Load page ONCE with config
+    // Load page ONCE with config (durationInFrames stays full for correct animation calculations)
     const pageUrl = `${url}?fps=${fps}&duration=${durationInFrames}&width=${width}&height=${height}`
     await page.goto(pageUrl, { waitUntil: 'networkidle' })
 
@@ -80,33 +91,36 @@ export async function renderVideo(options) {
 
     const renderStart = Date.now()
 
-    // Render each frame by updating the frame ref (no page reload!)
-    for (let frame = 0; frame < durationInFrames; frame++) {
+    // Render each frame in the specified range
+    for (let frame = startFrame; frame < actualEndFrame; frame++) {
       // Update frame number - Vue reactivity handles re-render
       await page.evaluate((f) => window.__PELLICULE_SET_FRAME__(f), frame)
 
-      // Screenshot
-      const framePath = join(outputDir, `frame-${String(frame).padStart(5, '0')}.png`)
+      // Screenshot - output frames are numbered from 0
+      const outputFrameNum = frame - startFrame
+      const framePath = join(outputDir, `frame-${String(outputFrameNum).padStart(5, '0')}.png`)
       await page.screenshot({ path: framePath })
 
       // Progress callback
       if (onProgress) {
         const elapsed = Date.now() - renderStart
-        const currentFps = (frame + 1) / (elapsed / 1000)
-        onProgress({ frame, total: durationInFrames, fps: currentFps })
+        const framesRendered = outputFrameNum + 1
+        const currentFps = framesRendered / (elapsed / 1000)
+        onProgress({ frame: outputFrameNum, total: framesToRender, fps: currentFps })
       }
 
       // Log progress every 10 frames
-      if (frame % 10 === 0 || frame === durationInFrames - 1) {
-        const percent = Math.round(((frame + 1) / durationInFrames) * 100)
+      const outputFrameIndex = frame - startFrame
+      if (outputFrameIndex % 10 === 0 || frame === actualEndFrame - 1) {
+        const percent = Math.round(((outputFrameIndex + 1) / framesToRender) * 100)
         const elapsed = Date.now() - renderStart
-        const framesPerSec = ((frame + 1) / (elapsed / 1000)).toFixed(1)
-        log(`Frame ${frame + 1}/${durationInFrames} (${percent}%) - ${framesPerSec} fps`)
+        const framesPerSec = ((outputFrameIndex + 1) / (elapsed / 1000)).toFixed(1)
+        log(`Frame ${outputFrameIndex + 1}/${framesToRender} (${percent}%) - ${framesPerSec} fps`)
       }
     }
 
     const renderTime = Date.now() - renderStart
-    log(`Rendered ${durationInFrames} frames in ${renderTime}ms (${(durationInFrames / (renderTime / 1000)).toFixed(1)} fps)`)
+    log(`Rendered ${framesToRender} frames in ${renderTime}ms (${(framesToRender / (renderTime / 1000)).toFixed(1)} fps)`)
 
   } finally {
     await browser.close()
@@ -116,5 +130,5 @@ export async function renderVideo(options) {
   log(`Total time: ${Date.now() - startTime}ms`)
   log(`Frames saved to ${outputDir}`)
 
-  return { framesDir: outputDir, totalFrames: durationInFrames }
+  return { framesDir: outputDir, totalFrames: framesToRender }
 }

package/src/composables.js

@@ -1,51 +0,0 @@
-import { inject, computed } from 'vue'
-
-/**
- * Injection keys for Pellicule context
- * Using Symbol.for() so keys are shared across module instances
- */
-export const FRAME_KEY = Symbol.for('pellicule-frame')
-export const CONFIG_KEY = Symbol.for('pellicule-config')
-
-/**
- * Get the current frame number.
- * Must be used within a Pellicule render context.
- *
- * @returns {import('vue').ComputedRef<number>} Current frame number
- *
- * @example
- * const frame = useFrame()
- * const opacity = computed(() => frame.value / 30) // fade in over 1 second at 30fps
- */
-export function useFrame() {
-  const frame = inject(FRAME_KEY)
-
-  if (frame === undefined) {
-    throw new Error(
-      'useFrame() must be used within a Pellicule render context'
-    )
-  }
-
-  return computed(() => frame.value)
-}
-
-/**
- * Get the video configuration (fps, duration, dimensions).
- * Must be used within a Pellicule render context.
- *
- * @returns {{ fps: number, durationInFrames: number, width: number, height: number }}
- *
- * @example
- * const { fps, durationInFrames, width, height } = useVideoConfig()
- */
-export function useVideoConfig() {
-  const config = inject(CONFIG_KEY)
-
-  if (!config) {
-    throw new Error(
-      'useVideoConfig() must be used within a Pellicule render context'
-    )
-  }
-
-  return config
-}