@t3lnet/sceneforge 1.0.10 → 1.0.12

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

@@ -53,7 +53,9 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
       "-c:v",
       "libx264",
       "-preset",
-      "fast",
+      "medium",
+      "-crf",
+      "18",
       "-c:a",
       "aac",
       "-b:a",
@@ -90,7 +92,9 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
       "-c:v",
       "libx264",
       "-preset",
-      "fast",
+      "medium",
+      "-crf",
+      "18",
       "-c:a",
       "aac",
       "-b:a",
@@ -117,7 +121,9 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
     "-c:v",
     "libx264",
     "-preset",
-    "fast",
+    "medium",
+    "-crf",
+    "18",
     "-c:a",
     "aac",
     "-b:a",

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

@@ -96,7 +96,9 @@ async function buildConcatWithIntroOutro(stepFiles, demoDir, introPath, outroPat
     "-c:v",
     "libx264",
     "-preset",
-    "fast",
+    "medium",
+    "-crf",
+    "18",
     "-c:a",
     "aac",
     "-b:a",
@@ -315,7 +317,9 @@ async function concatDemo(demoName, paths, options = {}) {
         "-c:v",
         "libx264",
         "-preset",
-        "fast",
+        "medium",
+        "-crf",
+        "18",
         "-c:a",
         "aac",
         "-b:a",

package/cli/commands/context.js

@@ -287,7 +287,7 @@ ${colors.blue}══════════════════════
 
     // Show what files will be created
     const { deployContext, getToolConfig, getSupportedTools } = await import(
-      "../../context/index.js"
+      "../../dist/index.js"
     );
 
     const tools = target === "all" ? getSupportedTools() : [target];
@@ -395,7 +395,7 @@ async function runDeployCommand(args) {
 
   // Dynamic import of context module
   const { deployContext, isValidTool, isValidFormat, getSupportedTools } = await import(
-    "../../context/index.js"
+    "../../dist/index.js"
   );
 
   // Validate target
@@ -487,7 +487,7 @@ async function runListCommand(args) {
 
   const outputDir = resolveRoot(output);
 
-  const { listDeployedContext } = await import("../../context/index.js");
+  const { listDeployedContext } = await import("../../dist/index.js");
 
   try {
     const { files } = await listDeployedContext(outputDir);
@@ -532,7 +532,7 @@ async function runRemoveCommand(args) {
   const outputDir = resolveRoot(output);
 
   const { removeContext, isValidTool, getSupportedTools } = await import(
-    "../../context/index.js"
+    "../../dist/index.js"
   );
 
   // Validate target
@@ -596,7 +596,7 @@ async function runPreviewCommand(args) {
   }
 
   const { previewContext, isValidTool, getSupportedTools } = await import(
-    "../../context/index.js"
+    "../../dist/index.js"
   );
 
   // Validate target
@@ -640,7 +640,7 @@ async function runSkillCommand(args) {
   const copy = getFlagValue(args, "--copy");
   const output = getFlagValue(args, "--output");
 
-  const { listSkills, getSkill } = await import("../../context/index.js");
+  const { listSkills, getSkill } = await import("../../dist/index.js");
 
   if (list) {
     try {

package/cli/commands/split-video.js

@@ -127,7 +127,9 @@ async function splitDemo(demoName, paths) {
         "-c:v",
         "libx264",
         "-preset",
-        "fast",
+        "medium",
+        "-crf",
+        "18",
         "-an",
         outputPath,
       ]);

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

@@ -104,6 +104,8 @@ sceneforge split --demo <name> [options]
 | `--demo` | Demo name (folder in output) |
 | `--output`, `-o` | Output directory |
 
+**Video Quality:** Encodes with H.264 (libx264), CRF 18, medium preset for high-quality output.
+
 ### voiceover
 Generate voiceover audio from scripts.
 
@@ -136,6 +138,8 @@ sceneforge add-audio --demo <name> [options]
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
 
+**Video Quality:** Re-encodes with H.264 (libx264), CRF 18, medium preset. Audio encoded as AAC at 192kbps.
+
 ### concat
 Concatenate step clips into final video.
 
@@ -149,6 +153,8 @@ sceneforge concat --demo <name> [options]
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
 
+**Video Quality:** Final encode with H.264 (libx264), CRF 18, medium preset. Includes `+faststart` for web streaming optimization. Audio encoded as AAC at 192kbps.
+
 ### doctor
 Run environment diagnostics.
 
@@ -234,3 +240,27 @@ sceneforge doctor
 # Record in headed mode with slow motion
 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:
+
+| 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 |
+
+**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
+
+**CRF Reference:**
+- 0 = Lossless (huge files)
+- 18 = Visually lossless (SceneForge default)
+- 23 = FFmpeg default
+- 28+ = Lower quality, smaller files

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

@@ -217,6 +217,26 @@ Aim for variance within ±500ms per step:
 - [ ] Volume consistent across steps
 - [ ] No unexpected pauses
 
+### Video Quality Check
+SceneForge uses high-quality encoding 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 |
+
+**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)
+
 ## Final Checklist
 
 - [ ] All steps have acceptable timing variance
@@ -225,4 +245,6 @@ Aim for variance within ±500ms per step:
 - [ ] No dead air or overlap issues
 - [ ] Intro provides adequate context
 - [ ] Outro concludes naturally
+- [ ] Video quality is sharp and clear
+- [ ] Audio is clear with consistent volume
 - [ ] Overall demo flows professionally

package/package.json

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