@t3lnet/sceneforge 1.0.15 → 1.0.17

package/README.md

@@ -72,6 +72,51 @@ npx sceneforge voice-cache prune --days 7  # Remove old entries
 
 Cache is stored in `.voice-cache/` in your project root.
 
+## Video Quality Settings
+
+SceneForge provides configurable video quality settings for the video processing pipeline.
+
+**Quality Presets:**
+
+| Preset | CRF | Encoding | Use Case |
+|--------|-----|----------|----------|
+| `low` | 28 | fast | Quick drafts, smaller files |
+| `medium` | 18 | medium | Default - balanced quality and size |
+| `high` | 10 | slow | Final delivery, best quality |
+
+**Supported Codecs:**
+
+| Codec | Description |
+|-------|-------------|
+| `libx264` | H.264 - excellent compatibility (default) |
+| `libx265` | H.265/HEVC - ~50% smaller files |
+
+**CLI Flags:**
+
+```bash
+--quality <preset>    # low, medium, high (default: medium)
+--crf <value>         # Override CRF (0-51, lower = better)
+--codec <codec>       # libx264 or libx265
+```
+
+**Examples:**
+
+```bash
+# High quality for final output
+npx sceneforge concat --demo my-demo --quality high
+
+# Smaller files with H.265
+npx sceneforge concat --demo my-demo --codec libx265
+
+# Custom CRF value
+npx sceneforge split --demo my-demo --crf 15
+```
+
+**Why it matters:**
+- Videos pass through multiple stages (split → add-audio → concat)
+- Higher quality (lower CRF) prevents generation loss
+- `high` preset (CRF 10) produces near-lossless quality for professional demos
+
 ## Notes
 
 - Voiceover generation uses ElevenLabs and requires `ELEVENLABS_API_KEY` + `ELEVENLABS_VOICE_ID`.

package/cli/commands/add-audio-to-steps.js

@@ -4,6 +4,12 @@ import { checkFFmpeg, getMediaDuration, runFFmpeg } from "../utils/media.js";
 import { getFlagValue, hasFlag } from "../utils/args.js";
 import { getOutputPaths, resolveRoot, readJson } from "../utils/paths.js";
 import { sanitizeFileSegment } from "../utils/sanitize.js";
+import {
+  getVideoEncodingArgs,
+  parseQualityArgs,
+  getQualityHelpText,
+  logQualitySettings,
+} from "../utils/quality.js";
 
 function printHelp() {
   console.log(`
@@ -19,20 +25,23 @@ Options:
   --root <path>         Project root (defaults to cwd)
   --output-dir <path>   Output directory (defaults to e2e/output or output)
   --help, -h            Show this help message
+${getQualityHelpText()}
 
 Output:
   Creates step_XX_<stepId>_with_audio.mp4 files in the videos/<demo>/ folder
 
 Examples:
   sceneforge add-audio --demo create-quote
-  sceneforge add-audio --all
+  sceneforge add-audio --demo create-quote --quality high
+  sceneforge add-audio --all --codec libx265
 `);
 }
 
-async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVideoPath) {
+async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVideoPath, qualityOptions = {}) {
   const videoDuration = await getMediaDuration(videoPath);
   const audioDuration = await getMediaDuration(audioPath);
   const targetDuration = audioDuration + padding;
+  const encodingArgs = getVideoEncodingArgs(qualityOptions);
 
   if (targetDuration <= videoDuration) {
     const padDuration = Math.max(0, videoDuration - audioDuration);
@@ -50,16 +59,7 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
       "[a]",
       "-t",
       String(videoDuration),
-      "-c:v",
-      "libx264",
-      "-preset",
-      "medium",
-      "-crf",
-      "18",
-      "-c:a",
-      "aac",
-      "-b:a",
-      "192k",
+      ...encodingArgs,
       outputPath,
     ]);
     return;
@@ -89,16 +89,7 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
       "[outv]",
       "-map",
       "2:a",
-      "-c:v",
-      "libx264",
-      "-preset",
-      "medium",
-      "-crf",
-      "18",
-      "-c:a",
-      "aac",
-      "-b:a",
-      "192k",
+      ...encodingArgs,
       "-t",
       String(targetDuration),
       outputPath,
@@ -118,24 +109,16 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
     "[v]",
     "-map",
     "1:a",
-    "-c:v",
-    "libx264",
-    "-preset",
-    "medium",
-    "-crf",
-    "18",
-    "-c:a",
-    "aac",
-    "-b:a",
-    "192k",
+    ...encodingArgs,
     "-t",
     String(targetDuration),
     outputPath,
   ]);
 }
 
-async function processDemo(demoName, paths, padding) {
+async function processDemo(demoName, paths, padding, qualityOptions = {}) {
   console.log(`\n[audio] Processing: ${demoName}\n`);
+  logQualitySettings(qualityOptions, "[audio]");
 
   const stepsManifestPath = path.join(paths.videosDir, demoName, "steps-manifest.json");
   let stepsManifest;
@@ -221,7 +204,7 @@ async function processDemo(demoName, paths, padding) {
     );
 
     try {
-      await addAudioToStep(step.videoFile, audioSegment.audioFile, outputPath, padding, nextVideoPath);
+      await addAudioToStep(step.videoFile, audioSegment.audioFile, outputPath, padding, nextVideoPath, qualityOptions);
       outputFiles.push(outputPath);
     } catch (error) {
       console.error(`[audio]   ${paddedIndex}. ${step.stepId}: ✗ Failed to process`);
@@ -254,7 +237,7 @@ async function processDemo(demoName, paths, padding) {
   console.log(`[audio]   Output: ${path.join(paths.videosDir, demoName)}`);
 }
 
-async function processAll(paths, padding) {
+async function processAll(paths, padding, qualityOptions = {}) {
   console.log("\n[audio] Processing all demos...\n");
 
   try {
@@ -285,7 +268,7 @@ async function processAll(paths, padding) {
     console.log(`[audio] Found ${demosToProcess.length} demo(s) to process\n`);
 
     for (const demo of demosToProcess) {
-      await processDemo(demo, paths, padding);
+      await processDemo(demo, paths, padding, qualityOptions);
     }
 
     await fs.rm(paths.tempDir, { recursive: true, force: true });
@@ -318,15 +301,16 @@ export async function runAddAudioCommand(argv) {
 
   const rootDir = resolveRoot(root);
   const paths = await getOutputPaths(rootDir, outputDir);
+  const qualityOptions = parseQualityArgs(args, getFlagValue, hasFlag);
 
   if (demo) {
-    await processDemo(demo, paths, padding);
+    await processDemo(demo, paths, padding, qualityOptions);
     await fs.rm(paths.tempDir, { recursive: true, force: true });
     return;
   }
 
   if (all) {
-    await processAll(paths, padding);
+    await processAll(paths, padding, qualityOptions);
     return;
   }
 

package/cli/commands/concat-final-videos.js

@@ -3,6 +3,14 @@ import * as path from "path";
 import { checkFFmpeg, getMediaDuration, runFFmpeg } from "../utils/media.js";
 import { getFlagValue, hasFlag } from "../utils/args.js";
 import { getOutputPaths, resolveRoot, readJson, toAbsolute } from "../utils/paths.js";
+import {
+  getVideoEncodingArgs,
+  parseQualityArgs,
+  getQualityHelpText,
+  logQualitySettings,
+  DEFAULT_AUDIO_CODEC,
+  DEFAULT_AUDIO_BITRATE,
+} from "../utils/quality.js";
 
 function printHelp() {
   console.log(`
@@ -24,12 +32,14 @@ Options:
   --root <path>         Project root (defaults to cwd)
   --output-dir <path>   Output directory (defaults to e2e/output or output)
   --help, -h            Show this help message
+${getQualityHelpText()}
 
 Examples:
   sceneforge concat --demo create-quote
+  sceneforge concat --demo create-quote --quality high
   sceneforge concat --demo create-quote --intro intro.mp4 --outro outro.mp4
   sceneforge concat --demo create-quote --music background.mp3 --music-volume 0.2
-  sceneforge concat --all
+  sceneforge concat --all --codec libx265
 `);
 }
 
@@ -55,7 +65,7 @@ async function loadMediaConfig(demoName, paths, rootDir) {
   }
 }
 
-async function buildConcatWithIntroOutro(stepFiles, demoDir, introPath, outroPath, outputPath) {
+async function buildConcatWithIntroOutro(stepFiles, demoDir, introPath, outroPath, outputPath, qualityOptions = {}) {
   const allInputs = [];
   const inputPaths = [];
   let inputIndex = 0;
@@ -83,6 +93,7 @@ async function buildConcatWithIntroOutro(stepFiles, demoDir, introPath, outroPat
 
   const concatInputs = inputPaths.map(({ index }) => `[${index}:v:0][${index}:a:0]`).join("");
   const filterGraph = `${concatInputs}concat=n=${inputPaths.length}:v=1:a=1[outv][outa]`;
+  const encodingArgs = getVideoEncodingArgs(qualityOptions);
 
   await runFFmpeg([
     "-y",
@@ -93,16 +104,7 @@ async function buildConcatWithIntroOutro(stepFiles, demoDir, introPath, outroPat
     "[outv]",
     "-map",
     "[outa]",
-    "-c:v",
-    "libx264",
-    "-preset",
-    "medium",
-    "-crf",
-    "18",
-    "-c:a",
-    "aac",
-    "-b:a",
-    "192k",
+    ...encodingArgs,
     "-movflags",
     "+faststart",
     outputPath,
@@ -194,9 +196,9 @@ async function addBackgroundMusic(videoPath, musicPath, outputPath, options = {}
     "-c:v",
     "copy",
     "-c:a",
-    "aac",
+    DEFAULT_AUDIO_CODEC,
     "-b:a",
-    "192k",
+    DEFAULT_AUDIO_BITRATE,
     "-movflags",
     "+faststart",
     outputPath,
@@ -205,6 +207,9 @@ async function addBackgroundMusic(videoPath, musicPath, outputPath, options = {}
 
 async function concatDemo(demoName, paths, options = {}) {
   console.log(`\n[concat] Processing: ${demoName}\n`);
+  if (options.qualityOptions) {
+    logQualitySettings(options.qualityOptions, "[concat]");
+  }
 
   const { rootDir, introOverride, outroOverride, musicOverride, musicOptions = {} } = options;
   const demoDir = path.join(paths.videosDir, demoName);
@@ -291,19 +296,23 @@ async function concatDemo(demoName, paths, options = {}) {
 
     console.log("[concat] Concatenating clips...");
 
+    const qualityOptions = options.qualityOptions || {};
+
     if (hasIntroOutro) {
       await buildConcatWithIntroOutro(
         stepFiles,
         demoDir,
         introPath,
         outroPath,
-        hasMusic ? tempConcatPath : outputPath
+        hasMusic ? tempConcatPath : outputPath,
+        qualityOptions
       );
     } else {
       // Original concatenation logic for steps only
       const inputArgs = stepFiles.flatMap((file) => ["-i", path.join(demoDir, file)]);
       const concatInputs = stepFiles.map((_, index) => `[${index}:v:0][${index}:a:0]`).join("");
       const filterGraph = `${concatInputs}concat=n=${stepFiles.length}:v=1:a=1[outv][outa]`;
+      const encodingArgs = getVideoEncodingArgs(qualityOptions);
 
       await runFFmpeg([
         "-y",
@@ -314,16 +323,7 @@ async function concatDemo(demoName, paths, options = {}) {
         "[outv]",
         "-map",
         "[outa]",
-        "-c:v",
-        "libx264",
-        "-preset",
-        "medium",
-        "-crf",
-        "18",
-        "-c:a",
-        "aac",
-        "-b:a",
-        "192k",
+        ...encodingArgs,
         "-movflags",
         "+faststart",
         hasMusic ? tempConcatPath : outputPath,
@@ -456,6 +456,7 @@ export async function runConcatCommand(argv) {
 
   const rootDir = resolveRoot(root);
   const paths = await getOutputPaths(rootDir, outputDir);
+  const qualityOptions = parseQualityArgs(args, getFlagValue, hasFlag);
 
   const options = {
     rootDir,
@@ -468,6 +469,7 @@ export async function runConcatCommand(argv) {
       fadeIn: musicFadeIn,
       fadeOut: musicFadeOut,
     },
+    qualityOptions,
   };
 
   if (demo) {

package/cli/commands/pipeline.js

@@ -3,6 +3,7 @@ import * as path from "path";
 import { loadDemoDefinition } from "@t3lnet/sceneforge";
 import { getFlagValue, hasFlag } from "../utils/args.js";
 import { ensureDir, getOutputPaths, resolveRoot, toAbsolute } from "../utils/paths.js";
+import { getQualityHelpText } from "../utils/quality.js";
 import { runRecordDemoCommand } from "./record-demo.js";
 import { runSplitVideoCommand } from "./split-video.js";
 import { runGenerateVoiceoverCommand } from "./generate-voiceover.js";
@@ -40,6 +41,7 @@ Media options (for final video):
   --music-loop           Loop music if shorter than video
   --music-fade-in <s>    Fade in duration for music (default: 1)
   --music-fade-out <s>   Fade out duration for music (default: 2)
+${getQualityHelpText()}
 
   --help, -h             Show this help message
 
@@ -48,6 +50,7 @@ Examples:
   sceneforge pipeline --demo create-quote --definitions-dir examples --base-url http://localhost:5173 --clean
   sceneforge pipeline --demo create-quote --output-dir output --resume --progress
   sceneforge pipeline --demo create-quote --intro assets/intro.mp4 --music assets/bg-music.mp3
+  sceneforge pipeline --demo create-quote --base-url http://localhost:5173 --quality high
 `);
 }
 
@@ -192,6 +195,11 @@ export async function runPipelineCommand(argv) {
   const musicFadeIn = getFlagValue(args, "--music-fade-in");
   const musicFadeOut = getFlagValue(args, "--music-fade-out");
 
+  // Video quality options
+  const quality = getFlagValue(args, "--quality");
+  const crf = getFlagValue(args, "--crf");
+  const codec = getFlagValue(args, "--codec");
+
   const rootDir = resolveRoot(root);
   const outputPaths = await getOutputPaths(rootDir, outputDir);
 
@@ -232,6 +240,12 @@ export async function runPipelineCommand(argv) {
       if (outro) console.log(`  - Outro: ${outro}`);
       if (music) console.log(`  - Music: ${music}`);
     }
+    if (quality || crf || codec) {
+      console.log("\nVideo quality options:");
+      if (quality) console.log(`  - Quality preset: ${quality}`);
+      if (crf) console.log(`  - CRF: ${crf}`);
+      if (codec) console.log(`  - Codec: ${codec}`);
+    }
     return;
   }
 
@@ -267,8 +281,20 @@ export async function runPipelineCommand(argv) {
     sharedArgs.push("--output-dir", outputDir);
   }
 
+  // Build quality args to pass through to video processing commands
+  const qualityArgs = [];
+  if (quality) {
+    qualityArgs.push("--quality", quality);
+  }
+  if (crf) {
+    qualityArgs.push("--crf", crf);
+  }
+  if (codec) {
+    qualityArgs.push("--codec", codec);
+  }
+
   await runStep("split", plan.split, () =>
-    runSplitVideoCommand(["--demo", demoName, ...sharedArgs])
+    runSplitVideoCommand(["--demo", demoName, ...sharedArgs, ...qualityArgs])
   );
 
   const voiceArgs = ["--demo", demoName, ...sharedArgs];
@@ -280,14 +306,14 @@ export async function runPipelineCommand(argv) {
   }
   await runStep("voiceover", plan.voiceover, () => runGenerateVoiceoverCommand(voiceArgs));
 
-  const audioArgs = ["--demo", demoName, ...sharedArgs];
+  const audioArgs = ["--demo", demoName, ...sharedArgs, ...qualityArgs];
   if (padding) {
     audioArgs.push("--padding", padding);
   }
   await runStep("add-audio", plan.addAudio, () => runAddAudioCommand(audioArgs));
 
-  // Build concat args with media options
-  const concatArgs = ["--demo", demoName, ...sharedArgs];
+  // Build concat args with media options and quality settings
+  const concatArgs = ["--demo", demoName, ...sharedArgs, ...qualityArgs];
   if (intro) {
     concatArgs.push("--intro", intro);
   }

package/cli/commands/split-video.js

@@ -4,6 +4,12 @@ import { checkFFmpeg, getMediaDuration, runFFmpeg } from "../utils/media.js";
 import { getOutputPaths, readJson, resolveRoot } from "../utils/paths.js";
 import { getFlagValue, hasFlag } from "../utils/args.js";
 import { sanitizeFileSegment } from "../utils/sanitize.js";
+import {
+  getVideoEncodingArgs,
+  parseQualityArgs,
+  getQualityHelpText,
+  logQualitySettings,
+} from "../utils/quality.js";
 
 function printHelp() {
   console.log(`
@@ -18,9 +24,12 @@ Options:
   --root <path>         Project root (defaults to cwd)
   --output-dir <path>   Output directory (defaults to e2e/output or output)
   --help, -h            Show this help message
+${getQualityHelpText()}
 
 Examples:
   sceneforge split --demo create-quote
+  sceneforge split --demo create-quote --quality high
+  sceneforge split --demo create-quote --crf 15 --codec libx265
   sceneforge split --all
 `);
 }
@@ -54,8 +63,9 @@ async function findVideoFile(demoName, videosDir, testResultsDir) {
   return null;
 }
 
-async function splitDemo(demoName, paths) {
+async function splitDemo(demoName, paths, qualityOptions = {}) {
   console.log(`\n[split] Processing: ${demoName}\n`);
+  logQualitySettings(qualityOptions, "[split]");
 
   const scriptPath = path.join(paths.scriptsDir, `${demoName}.json`);
   let script;
@@ -116,6 +126,7 @@ async function splitDemo(demoName, paths) {
     );
 
     try {
+      const encodingArgs = getVideoEncodingArgs({ ...qualityOptions, includeAudio: false });
       await runFFmpeg([
         "-y",
         "-i",
@@ -124,12 +135,7 @@ async function splitDemo(demoName, paths) {
         String(startSec),
         "-t",
         String(duration),
-        "-c:v",
-        "libx264",
-        "-preset",
-        "medium",
-        "-crf",
-        "18",
+        ...encodingArgs,
         "-an",
         outputPath,
       ]);
@@ -175,7 +181,7 @@ async function splitDemo(demoName, paths) {
   console.log(`[split]   Manifest: ${manifestPath}`);
 }
 
-async function splitAll(paths) {
+async function splitAll(paths, qualityOptions = {}) {
   console.log("\n[split] Processing all demos...\n");
 
   try {
@@ -193,7 +199,7 @@ async function splitAll(paths) {
 
     for (const file of scriptFiles) {
       const demoName = path.basename(file, ".json");
-      await splitDemo(demoName, paths);
+      await splitDemo(demoName, paths, qualityOptions);
     }
 
     console.log("\n[split] All demos processed!");
@@ -223,14 +229,15 @@ export async function runSplitVideoCommand(argv) {
 
   const rootDir = resolveRoot(root);
   const paths = await getOutputPaths(rootDir, outputDir);
+  const qualityOptions = parseQualityArgs(args, getFlagValue, hasFlag);
 
   if (demo) {
-    await splitDemo(demo, paths);
+    await splitDemo(demo, paths, qualityOptions);
     return;
   }
 
   if (all) {
-    await splitAll(paths);
+    await splitAll(paths, qualityOptions);
     return;
   }
 

package/cli/utils/quality.js

@@ -0,0 +1,154 @@
+/**
+ * Video quality configuration for FFmpeg encoding
+ *
+ * Quality Presets:
+ * - low: Fast encoding, smaller files, suitable for drafts
+ * - medium: Balanced quality and file size (default)
+ * - high: Best quality, larger files, suitable for final delivery
+ *
+ * Supported Codecs:
+ * - libx264: H.264, excellent compatibility (default)
+ * - libx265: H.265/HEVC, ~50% smaller files, slower encoding
+ */
+
+export const QUALITY_PRESETS = {
+  low: {
+    crf: 28,
+    preset: "fast",
+    description: "Fast encoding, smaller files, suitable for drafts",
+  },
+  medium: {
+    crf: 18,
+    preset: "medium",
+    description: "Balanced quality and file size (default)",
+  },
+  high: {
+    crf: 10,
+    preset: "slow",
+    description: "Best quality, larger files, suitable for final delivery",
+  },
+};
+
+export const SUPPORTED_CODECS = {
+  libx264: {
+    name: "H.264",
+    description: "Excellent compatibility, plays everywhere",
+    crfRange: "0-51 (lower = better)",
+  },
+  libx265: {
+    name: "H.265/HEVC",
+    description: "~50% smaller files, slower encoding, good compatibility",
+    crfRange: "0-51 (lower = better)",
+  },
+};
+
+export const DEFAULT_CODEC = "libx264";
+export const DEFAULT_QUALITY = "medium";
+export const DEFAULT_AUDIO_CODEC = "aac";
+export const DEFAULT_AUDIO_BITRATE = "192k";
+
+/**
+ * Get video encoding arguments for FFmpeg
+ * @param {Object} options
+ * @param {string} [options.quality] - Quality preset: low, medium, high
+ * @param {number} [options.crf] - Override CRF value (0-51, lower = better)
+ * @param {string} [options.codec] - Video codec: libx264, libx265
+ * @param {boolean} [options.includeAudio] - Include audio encoding args
+ * @returns {string[]} FFmpeg arguments for video encoding
+ */
+export function getVideoEncodingArgs(options = {}) {
+  const {
+    quality = DEFAULT_QUALITY,
+    crf: crfOverride,
+    codec = DEFAULT_CODEC,
+    includeAudio = true,
+  } = options;
+
+  const preset = QUALITY_PRESETS[quality] || QUALITY_PRESETS[DEFAULT_QUALITY];
+  // Only use crfOverride if it's a valid finite number
+  const crf = (crfOverride !== undefined && Number.isFinite(crfOverride)) ? crfOverride : preset.crf;
+  const encodingPreset = preset.preset;
+
+  const args = ["-c:v", codec, "-preset", encodingPreset, "-crf", String(crf)];
+
+  if (includeAudio) {
+    args.push("-c:a", DEFAULT_AUDIO_CODEC, "-b:a", DEFAULT_AUDIO_BITRATE);
+  }
+
+  return args;
+}
+
+/**
+ * Parse quality-related CLI arguments
+ * @param {string[]} args - CLI arguments
+ * @param {Function} getFlagValue - Function to get flag values
+ * @param {Function} hasFlag - Function to check flag presence
+ * @returns {Object} Parsed quality options
+ */
+export function parseQualityArgs(args, getFlagValue, hasFlag) {
+  const quality = getFlagValue(args, "--quality") || DEFAULT_QUALITY;
+  const crfValue = getFlagValue(args, "--crf");
+  const codec = getFlagValue(args, "--codec") || DEFAULT_CODEC;
+
+  // Validate quality preset
+  if (!QUALITY_PRESETS[quality]) {
+    console.warn(
+      `[warning] Unknown quality preset "${quality}", using "${DEFAULT_QUALITY}"`
+    );
+  }
+
+  // Validate codec
+  if (!SUPPORTED_CODECS[codec]) {
+    console.warn(
+      `[warning] Unknown codec "${codec}", using "${DEFAULT_CODEC}"`
+    );
+  }
+
+  // Parse CRF value, only set if it's a valid number
+  let crf = undefined;
+  if (crfValue !== undefined && crfValue !== null && crfValue !== "") {
+    const parsed = parseInt(crfValue, 10);
+    if (!Number.isNaN(parsed)) {
+      crf = parsed;
+    }
+  }
+
+  return {
+    quality: QUALITY_PRESETS[quality] ? quality : DEFAULT_QUALITY,
+    crf,
+    codec: SUPPORTED_CODECS[codec] ? codec : DEFAULT_CODEC,
+  };
+}
+
+/**
+ * Get help text for quality options
+ * @returns {string} Help text for quality CLI options
+ */
+export function getQualityHelpText() {
+  return `
+Video Quality Options:
+  --quality <preset>    Quality preset: low, medium, high (default: medium)
+                        - low: CRF 28, fast preset (smaller files, quick encoding)
+                        - medium: CRF 18, medium preset (balanced)
+                        - high: CRF 10, slow preset (best quality, larger files)
+  --crf <value>         Override CRF value (0-51, lower = better quality)
+  --codec <codec>       Video codec: libx264, libx265 (default: libx264)
+                        - libx264: H.264, excellent compatibility
+                        - libx265: H.265/HEVC, ~50% smaller files`;
+}
+
+/**
+ * Log the quality settings being used
+ * @param {Object} options - Quality options
+ * @param {string} prefix - Log prefix (e.g., "[split]")
+ */
+export function logQualitySettings(options, prefix = "") {
+  const { quality, crf, codec } = options;
+  const preset = QUALITY_PRESETS[quality] || QUALITY_PRESETS[DEFAULT_QUALITY];
+  const effectiveCrf = crf !== undefined ? crf : preset.crf;
+  const codecInfo = SUPPORTED_CODECS[codec] || SUPPORTED_CODECS[DEFAULT_CODEC];
+
+  console.log(
+    `${prefix} Quality: ${quality} (CRF ${effectiveCrf}, ${preset.preset} preset, ${codecInfo.name})`
+  );
+}

package/context/templates/base/cli-reference.md

@@ -103,8 +103,11 @@ sceneforge split --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name (folder in output) |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
 
-**Video Quality:** Encodes with H.264 (libx264), CRF 18, medium preset for high-quality output.
+**Video Quality:** Configurable via `--quality` preset or `--crf`/`--codec` flags. Default: medium preset (CRF 18, libx264).
 
 ### voiceover
 Generate voiceover audio from scripts.
@@ -137,8 +140,11 @@ sceneforge add-audio --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
 
-**Video Quality:** Re-encodes with H.264 (libx264), CRF 18, medium preset. Audio encoded as AAC at 192kbps.
+**Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Audio: AAC 192kbps.
 
 ### concat
 Concatenate step clips into final video.
@@ -152,8 +158,15 @@ sceneforge concat --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
+| `--intro` | Intro video to prepend |
+| `--outro` | Outro video to append |
+| `--music` | Background music file |
+| `--music-volume` | Music volume 0-1 (default: 0.15) |
 
-**Video Quality:** Final encode with H.264 (libx264), CRF 18, medium preset. Includes `+faststart` for web streaming optimization. Audio encoded as AAC at 192kbps.
+**Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Includes `+faststart` for web streaming. Audio: AAC 192kbps.
 
 ### doctor
 Run environment diagnostics.
@@ -249,24 +262,55 @@ sceneforge record -d demo.yaml -b http://localhost:3000 --headed --slowmo 500
 
 ## Video Quality
 
-SceneForge uses high-quality FFmpeg encoding settings optimized for multi-pass video processing:
+SceneForge provides configurable video quality settings via CLI flags on `split`, `add-audio`, and `concat` commands.
 
-| Setting | Value | Purpose |
-|---------|-------|---------|
-| Codec | `libx264` | H.264 for broad compatibility |
-| Preset | `medium` | Balanced quality/speed tradeoff |
-| CRF | `18` | High quality (visually lossless) |
-| Audio | `aac @ 192k` | High-quality audio |
-| Flags | `+faststart` | Web streaming optimization |
+### Quality Presets
+
+| Preset | CRF | Encoding | Use Case |
+|--------|-----|----------|----------|
+| `low` | 28 | fast | Quick drafts, smaller files |
+| `medium` | 18 | medium | Default - balanced quality and size |
+| `high` | 10 | slow | Final delivery, best quality |
+
+### Supported Codecs
+
+| Codec | Name | Description |
+|-------|------|-------------|
+| `libx264` | H.264 | Excellent compatibility (default) |
+| `libx265` | H.265/HEVC | ~50% smaller files, slower encoding |
+
+### CLI Flags
+
+```bash
+--quality <preset>    # low, medium, high (default: medium)
+--crf <value>         # Override CRF (0-51, lower = better)
+--codec <codec>       # libx264 or libx265 (default: libx264)
+```
+
+### Examples
+
+```bash
+# High quality for final output
+sceneforge concat --demo my-demo --quality high
+
+# Smaller files with H.265 codec
+sceneforge concat --demo my-demo --codec libx265
+
+# Custom CRF for fine control
+sceneforge split --demo my-demo --crf 15
+```
+
+### Why Quality Matters
 
-**Why these settings:**
 - Videos go through multiple processing stages (split → add-audio → concat)
 - Each re-encoding can degrade quality (generation loss)
-- CRF 18 preserves quality across all stages
-- Medium preset provides good compression without sacrificing quality
+- Higher quality settings (lower CRF) preserve fidelity across stages
+- The `high` preset (CRF 10) produces near-lossless quality
+
+### CRF Reference
 
-**CRF Reference:**
 - 0 = Lossless (huge files)
-- 18 = Visually lossless (SceneForge default)
+- 10 = Near-lossless (high preset)
+- 18 = Visually lossless (medium preset, default)
 - 23 = FFmpeg default
-- 28+ = Lower quality, smaller files
+- 28 = Lower quality (low preset)

package/context/templates/stages/stage4-rebalancing.md

@@ -218,24 +218,26 @@ Aim for variance within ±500ms per step:
 - [ ] No unexpected pauses
 
 ### Video Quality Check
-SceneForge uses high-quality encoding settings to preserve video fidelity:
+SceneForge provides configurable quality settings to preserve video fidelity:
 - [ ] Video appears sharp (no compression artifacts)
 - [ ] Colors are accurate (no banding)
 - [ ] Text is readable (no blur from compression)
 - [ ] No visible quality degradation between steps
 
-**Encoding Settings Used:**
-| Setting | Value | Purpose |
-|---------|-------|---------|
-| Codec | `libx264` | H.264 for compatibility |
-| CRF | `18` | High quality (visually lossless) |
-| Preset | `medium` | Balanced quality/speed |
-| Audio | `aac @ 192k` | High-quality audio |
+**Quality Presets:**
+| Preset | CRF | Encoding | Use Case |
+|--------|-----|----------|----------|
+| `low` | 28 | fast | Quick drafts |
+| `medium` | 18 | medium | Default - balanced |
+| `high` | 10 | slow | Final delivery |
+
+**CLI Flags:** `--quality`, `--crf`, `--codec` (available on split, add-audio, concat)
 
 **If you notice quality issues:**
-1. Ensure source recording is high quality (check `output/videos/<demo>.webm`)
-2. Re-run the pipeline to regenerate all clips
-3. Check available disk space (low space can affect encoding)
+1. Re-run with `--quality high` for better fidelity
+2. Ensure source recording is high quality (check `output/videos/<demo>.webm`)
+3. Try `--codec libx265` for better compression at same quality
+4. Check available disk space (low space can affect encoding)
 
 ## Final Checklist
 

package/dist/templates/base/cli-reference.md

@@ -103,8 +103,11 @@ sceneforge split --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name (folder in output) |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
 
-**Video Quality:** Encodes with H.264 (libx264), CRF 18, medium preset for high-quality output.
+**Video Quality:** Configurable via `--quality` preset or `--crf`/`--codec` flags. Default: medium preset (CRF 18, libx264).
 
 ### voiceover
 Generate voiceover audio from scripts.
@@ -137,8 +140,11 @@ sceneforge add-audio --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
 
-**Video Quality:** Re-encodes with H.264 (libx264), CRF 18, medium preset. Audio encoded as AAC at 192kbps.
+**Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Audio: AAC 192kbps.
 
 ### concat
 Concatenate step clips into final video.
@@ -152,8 +158,15 @@ sceneforge concat --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
+| `--intro` | Intro video to prepend |
+| `--outro` | Outro video to append |
+| `--music` | Background music file |
+| `--music-volume` | Music volume 0-1 (default: 0.15) |
 
-**Video Quality:** Final encode with H.264 (libx264), CRF 18, medium preset. Includes `+faststart` for web streaming optimization. Audio encoded as AAC at 192kbps.
+**Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Includes `+faststart` for web streaming. Audio: AAC 192kbps.
 
 ### doctor
 Run environment diagnostics.
@@ -249,24 +262,55 @@ sceneforge record -d demo.yaml -b http://localhost:3000 --headed --slowmo 500
 
 ## Video Quality
 
-SceneForge uses high-quality FFmpeg encoding settings optimized for multi-pass video processing:
+SceneForge provides configurable video quality settings via CLI flags on `split`, `add-audio`, and `concat` commands.
 
-| Setting | Value | Purpose |
-|---------|-------|---------|
-| Codec | `libx264` | H.264 for broad compatibility |
-| Preset | `medium` | Balanced quality/speed tradeoff |
-| CRF | `18` | High quality (visually lossless) |
-| Audio | `aac @ 192k` | High-quality audio |
-| Flags | `+faststart` | Web streaming optimization |
+### Quality Presets
+
+| Preset | CRF | Encoding | Use Case |
+|--------|-----|----------|----------|
+| `low` | 28 | fast | Quick drafts, smaller files |
+| `medium` | 18 | medium | Default - balanced quality and size |
+| `high` | 10 | slow | Final delivery, best quality |
+
+### Supported Codecs
+
+| Codec | Name | Description |
+|-------|------|-------------|
+| `libx264` | H.264 | Excellent compatibility (default) |
+| `libx265` | H.265/HEVC | ~50% smaller files, slower encoding |
+
+### CLI Flags
+
+```bash
+--quality <preset>    # low, medium, high (default: medium)
+--crf <value>         # Override CRF (0-51, lower = better)
+--codec <codec>       # libx264 or libx265 (default: libx264)
+```
+
+### Examples
+
+```bash
+# High quality for final output
+sceneforge concat --demo my-demo --quality high
+
+# Smaller files with H.265 codec
+sceneforge concat --demo my-demo --codec libx265
+
+# Custom CRF for fine control
+sceneforge split --demo my-demo --crf 15
+```
+
+### Why Quality Matters
 
-**Why these settings:**
 - Videos go through multiple processing stages (split → add-audio → concat)
 - Each re-encoding can degrade quality (generation loss)
-- CRF 18 preserves quality across all stages
-- Medium preset provides good compression without sacrificing quality
+- Higher quality settings (lower CRF) preserve fidelity across stages
+- The `high` preset (CRF 10) produces near-lossless quality
+
+### CRF Reference
 
-**CRF Reference:**
 - 0 = Lossless (huge files)
-- 18 = Visually lossless (SceneForge default)
+- 10 = Near-lossless (high preset)
+- 18 = Visually lossless (medium preset, default)
 - 23 = FFmpeg default
-- 28+ = Lower quality, smaller files
+- 28 = Lower quality (low preset)

package/dist/templates/stages/stage4-rebalancing.md

@@ -218,24 +218,26 @@ Aim for variance within ±500ms per step:
 - [ ] No unexpected pauses
 
 ### Video Quality Check
-SceneForge uses high-quality encoding settings to preserve video fidelity:
+SceneForge provides configurable quality settings to preserve video fidelity:
 - [ ] Video appears sharp (no compression artifacts)
 - [ ] Colors are accurate (no banding)
 - [ ] Text is readable (no blur from compression)
 - [ ] No visible quality degradation between steps
 
-**Encoding Settings Used:**
-| Setting | Value | Purpose |
-|---------|-------|---------|
-| Codec | `libx264` | H.264 for compatibility |
-| CRF | `18` | High quality (visually lossless) |
-| Preset | `medium` | Balanced quality/speed |
-| Audio | `aac @ 192k` | High-quality audio |
+**Quality Presets:**
+| Preset | CRF | Encoding | Use Case |
+|--------|-----|----------|----------|
+| `low` | 28 | fast | Quick drafts |
+| `medium` | 18 | medium | Default - balanced |
+| `high` | 10 | slow | Final delivery |
+
+**CLI Flags:** `--quality`, `--crf`, `--codec` (available on split, add-audio, concat)
 
 **If you notice quality issues:**
-1. Ensure source recording is high quality (check `output/videos/<demo>.webm`)
-2. Re-run the pipeline to regenerate all clips
-3. Check available disk space (low space can affect encoding)
+1. Re-run with `--quality high` for better fidelity
+2. Ensure source recording is high quality (check `output/videos/<demo>.webm`)
+3. Try `--codec libx265` for better compression at same quality
+4. Check available disk space (low space can affect encoding)
 
 ## Final Checklist
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t3lnet/sceneforge",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "SceneForge runner and generation utilities for YAML-driven demos",
   "license": "MIT",
   "author": "T3LNET",