@t3lnet/sceneforge 1.0.17 → 1.0.19

package/README.md

@@ -117,6 +117,71 @@ npx sceneforge split --demo my-demo --crf 15
 - Higher quality (lower CRF) prevents generation loss
 - `high` preset (CRF 10) produces near-lossless quality for professional demos
 
+## Viewport Settings (Recording)
+
+Control browser viewport size and zoom level during recording:
+
+```bash
+--viewport <WxH|preset>      # Viewport size (default: 1440x900)
+                             # Presets: 720p, 1080p, 1440p, 4k
+--width <px>                 # Viewport width
+--height <px>                # Viewport height
+--zoom <percent>             # Browser zoom: 100, 150, 200 (default: 100)
+--device-scale-factor <n>    # Device pixel ratio: 1, 1.5, 2
+```
+
+**Examples:**
+
+```bash
+# Record at 1080p
+npx sceneforge record --definition demo.yaml --base-url http://localhost:5173 --viewport 1080p
+
+# Record with zoom for extra detail
+npx sceneforge record --definition demo.yaml --base-url http://localhost:5173 \
+  --viewport 1920x1080 --zoom 150
+```
+
+## Output Dimensions (Video Processing)
+
+Control final video resolution with support for different platforms and aspect ratios:
+
+**Presets:**
+
+| Preset | Resolution | Use Case |
+|--------|------------|----------|
+| `720p` | 1280x720 | HD landscape |
+| `1080p` | 1920x1080 | Full HD landscape |
+| `4k` | 3840x2160 | 4K UHD |
+| `tiktok` | 1080x1920 | TikTok/Reels (portrait) |
+| `shorts` | 1080x1920 | YouTube Shorts (portrait) |
+| `square` | 1080x1080 | Instagram posts |
+
+```bash
+--output-size <WxH|preset>   # Output video dimensions
+--output-width <px>          # Output width (-1 for auto)
+--output-height <px>         # Output height (-1 for auto)
+```
+
+**Examples:**
+
+```bash
+# Standard 1080p output
+npx sceneforge concat --demo my-demo --output-size 1080p
+
+# TikTok/YouTube Shorts (portrait)
+npx sceneforge pipeline --demo my-demo --base-url http://localhost:5173 \
+  --output-size tiktok --quality high
+
+# Square for Instagram
+npx sceneforge concat --demo my-demo --output-size square
+
+# Full pipeline with all video options
+npx sceneforge pipeline --demo my-demo --base-url http://localhost:5173 \
+  --viewport 1080p --zoom 150 \
+  --output-size 1080p \
+  --quality high
+```
+
 ## Notes
 
 - Voiceover generation uses ElevenLabs and requires `ELEVENLABS_API_KEY` + `ELEVENLABS_VOICE_ID`.

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

@@ -10,6 +10,12 @@ import {
   getQualityHelpText,
   logQualitySettings,
 } from "../utils/quality.js";
+import {
+  parseOutputDimensions,
+  getOutputDimensionsHelpText,
+  getScaleFilterArgs,
+  logOutputDimensions,
+} from "../utils/dimensions.js";
 
 function printHelp() {
   console.log(`
@@ -26,6 +32,7 @@ Options:
   --output-dir <path>   Output directory (defaults to e2e/output or output)
   --help, -h            Show this help message
 ${getQualityHelpText()}
+${getOutputDimensionsHelpText()}
 
 Output:
   Creates step_XX_<stepId>_with_audio.mp4 files in the videos/<demo>/ folder
@@ -33,18 +40,32 @@ Output:
 Examples:
   sceneforge add-audio --demo create-quote
   sceneforge add-audio --demo create-quote --quality high
+  sceneforge add-audio --demo create-quote --output-size 1080p
   sceneforge add-audio --all --codec libx265
 `);
 }
 
-async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVideoPath, qualityOptions = {}) {
+// Build scale filter string for chaining in filter_complex
+function buildScaleFilter(outputDimensions) {
+  if (!outputDimensions) return "";
+  const { width, height } = outputDimensions;
+  if (width === -1 || height === -1) {
+    return `scale=${width}:${height}`;
+  }
+  return `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:black`;
+}
+
+async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVideoPath, qualityOptions = {}, outputDimensions = null) {
   const videoDuration = await getMediaDuration(videoPath);
   const audioDuration = await getMediaDuration(audioPath);
   const targetDuration = audioDuration + padding;
   const encodingArgs = getVideoEncodingArgs(qualityOptions);
+  const scaleFilter = buildScaleFilter(outputDimensions);
 
   if (targetDuration <= videoDuration) {
     const padDuration = Math.max(0, videoDuration - audioDuration);
+    // For this case, use -vf for scaling since filter_complex only handles audio
+    const videoFilterArgs = scaleFilter ? ["-vf", scaleFilter] : [];
     await runFFmpeg([
       "-y",
       "-i",
@@ -53,6 +74,7 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
       audioPath,
       "-filter_complex",
       `[1:a]apad=pad_dur=${padDuration}[a]`,
+      ...videoFilterArgs,
       "-map",
       "0:v",
       "-map",
@@ -69,11 +91,13 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
 
   if (nextVideoPath) {
     const stillDuration = 0.04;
+    // Chain scale filter into the filter_complex output
+    const scaleChain = scaleFilter ? `,${scaleFilter}` : "";
     const filterGraph =
       `[1:v]trim=start=0:end=${stillDuration},setpts=PTS-STARTPTS,` +
       `tpad=stop_mode=clone:stop_duration=${extensionNeeded},` +
       `trim=duration=${extensionNeeded}[next_still];` +
-      `[0:v][next_still]concat=n=2:v=1:a=0[outv]`;
+      `[0:v][next_still]concat=n=2:v=1:a=0${scaleChain}[outv]`;
 
     await runFFmpeg([
       "-y",
@@ -97,6 +121,8 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
     return;
   }
 
+  // Chain scale filter into the filter_complex output
+  const scaleChain = scaleFilter ? `,${scaleFilter}` : "";
   await runFFmpeg([
     "-y",
     "-i",
@@ -104,7 +130,7 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
     "-i",
     audioPath,
     "-filter_complex",
-    `[0:v]tpad=stop_mode=clone:stop_duration=${extensionNeeded}[v]`,
+    `[0:v]tpad=stop_mode=clone:stop_duration=${extensionNeeded}${scaleChain}[v]`,
     "-map",
     "[v]",
     "-map",
@@ -116,9 +142,10 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
   ]);
 }
 
-async function processDemo(demoName, paths, padding, qualityOptions = {}) {
+async function processDemo(demoName, paths, padding, qualityOptions = {}, outputDimensions = null) {
   console.log(`\n[audio] Processing: ${demoName}\n`);
   logQualitySettings(qualityOptions, "[audio]");
+  logOutputDimensions(outputDimensions, "[audio]");
 
   const stepsManifestPath = path.join(paths.videosDir, demoName, "steps-manifest.json");
   let stepsManifest;
@@ -204,7 +231,7 @@ async function processDemo(demoName, paths, padding, qualityOptions = {}) {
     );
 
     try {
-      await addAudioToStep(step.videoFile, audioSegment.audioFile, outputPath, padding, nextVideoPath, qualityOptions);
+      await addAudioToStep(step.videoFile, audioSegment.audioFile, outputPath, padding, nextVideoPath, qualityOptions, outputDimensions);
       outputFiles.push(outputPath);
     } catch (error) {
       console.error(`[audio]   ${paddedIndex}. ${step.stepId}: ✗ Failed to process`);
@@ -237,7 +264,7 @@ async function processDemo(demoName, paths, padding, qualityOptions = {}) {
   console.log(`[audio]   Output: ${path.join(paths.videosDir, demoName)}`);
 }
 
-async function processAll(paths, padding, qualityOptions = {}) {
+async function processAll(paths, padding, qualityOptions = {}, outputDimensions = null) {
   console.log("\n[audio] Processing all demos...\n");
 
   try {
@@ -268,7 +295,7 @@ async function processAll(paths, padding, qualityOptions = {}) {
     console.log(`[audio] Found ${demosToProcess.length} demo(s) to process\n`);
 
     for (const demo of demosToProcess) {
-      await processDemo(demo, paths, padding, qualityOptions);
+      await processDemo(demo, paths, padding, qualityOptions, outputDimensions);
     }
 
     await fs.rm(paths.tempDir, { recursive: true, force: true });
@@ -302,15 +329,16 @@ export async function runAddAudioCommand(argv) {
   const rootDir = resolveRoot(root);
   const paths = await getOutputPaths(rootDir, outputDir);
   const qualityOptions = parseQualityArgs(args, getFlagValue, hasFlag);
+  const outputDimensions = parseOutputDimensions(args, getFlagValue);
 
   if (demo) {
-    await processDemo(demo, paths, padding, qualityOptions);
+    await processDemo(demo, paths, padding, qualityOptions, outputDimensions);
     await fs.rm(paths.tempDir, { recursive: true, force: true });
     return;
   }
 
   if (all) {
-    await processAll(paths, padding, qualityOptions);
+    await processAll(paths, padding, qualityOptions, outputDimensions);
     return;
   }
 

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

@@ -11,6 +11,11 @@ import {
   DEFAULT_AUDIO_CODEC,
   DEFAULT_AUDIO_BITRATE,
 } from "../utils/quality.js";
+import {
+  parseOutputDimensions,
+  getOutputDimensionsHelpText,
+  logOutputDimensions,
+} from "../utils/dimensions.js";
 
 function printHelp() {
   console.log(`
@@ -33,10 +38,13 @@ Options:
   --output-dir <path>   Output directory (defaults to e2e/output or output)
   --help, -h            Show this help message
 ${getQualityHelpText()}
+${getOutputDimensionsHelpText()}
 
 Examples:
   sceneforge concat --demo create-quote
   sceneforge concat --demo create-quote --quality high
+  sceneforge concat --demo create-quote --output-size 1080p
+  sceneforge concat --demo create-quote --output-size tiktok  # 1080x1920 vertical
   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 --codec libx265
@@ -65,7 +73,17 @@ async function loadMediaConfig(demoName, paths, rootDir) {
   }
 }
 
-async function buildConcatWithIntroOutro(stepFiles, demoDir, introPath, outroPath, outputPath, qualityOptions = {}) {
+// Build scale filter string for use in filter_complex
+function buildScaleFilter(outputDimensions) {
+  if (!outputDimensions) return "";
+  const { width, height } = outputDimensions;
+  if (width === -1 || height === -1) {
+    return `scale=${width}:${height}`;
+  }
+  return `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:black`;
+}
+
+async function buildConcatWithIntroOutro(stepFiles, demoDir, introPath, outroPath, outputPath, qualityOptions = {}, outputDimensions = null) {
   const allInputs = [];
   const inputPaths = [];
   let inputIndex = 0;
@@ -92,7 +110,11 @@ 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 scaleFilter = buildScaleFilter(outputDimensions);
+  // If scaling, we need to output concat to temp labels, then apply scale to video only
+  const filterGraph = scaleFilter
+    ? `${concatInputs}concat=n=${inputPaths.length}:v=1:a=1[tmpv][outa];[tmpv]${scaleFilter}[outv]`
+    : `${concatInputs}concat=n=${inputPaths.length}:v=1:a=1[outv][outa]`;
   const encodingArgs = getVideoEncodingArgs(qualityOptions);
 
   await runFFmpeg([
@@ -210,6 +232,9 @@ async function concatDemo(demoName, paths, options = {}) {
   if (options.qualityOptions) {
     logQualitySettings(options.qualityOptions, "[concat]");
   }
+  if (options.outputDimensions) {
+    logOutputDimensions(options.outputDimensions, "[concat]");
+  }
 
   const { rootDir, introOverride, outroOverride, musicOverride, musicOptions = {} } = options;
   const demoDir = path.join(paths.videosDir, demoName);
@@ -297,6 +322,7 @@ async function concatDemo(demoName, paths, options = {}) {
     console.log("[concat] Concatenating clips...");
 
     const qualityOptions = options.qualityOptions || {};
+    const outputDimensions = options.outputDimensions || null;
 
     if (hasIntroOutro) {
       await buildConcatWithIntroOutro(
@@ -305,13 +331,18 @@ async function concatDemo(demoName, paths, options = {}) {
         introPath,
         outroPath,
         hasMusic ? tempConcatPath : outputPath,
-        qualityOptions
+        qualityOptions,
+        outputDimensions
       );
     } 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 scaleFilter = buildScaleFilter(outputDimensions);
+      // If scaling, we need to output concat to temp labels, then apply scale to video only
+      const filterGraph = scaleFilter
+        ? `${concatInputs}concat=n=${stepFiles.length}:v=1:a=1[tmpv][outa];[tmpv]${scaleFilter}[outv]`
+        : `${concatInputs}concat=n=${stepFiles.length}:v=1:a=1[outv][outa]`;
       const encodingArgs = getVideoEncodingArgs(qualityOptions);
 
       await runFFmpeg([
@@ -457,6 +488,7 @@ export async function runConcatCommand(argv) {
   const rootDir = resolveRoot(root);
   const paths = await getOutputPaths(rootDir, outputDir);
   const qualityOptions = parseQualityArgs(args, getFlagValue, hasFlag);
+  const outputDimensions = parseOutputDimensions(args, getFlagValue);
 
   const options = {
     rootDir,
@@ -470,6 +502,7 @@ export async function runConcatCommand(argv) {
       fadeOut: musicFadeOut,
     },
     qualityOptions,
+    outputDimensions,
   };
 
   if (demo) {

package/cli/commands/pipeline.js

@@ -4,6 +4,7 @@ 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 { getViewportHelpText, getOutputDimensionsHelpText } from "../utils/dimensions.js";
 import { runRecordDemoCommand } from "./record-demo.js";
 import { runSplitVideoCommand } from "./split-video.js";
 import { runGenerateVoiceoverCommand } from "./generate-voiceover.js";
@@ -42,6 +43,8 @@ Media options (for final video):
   --music-fade-in <s>    Fade in duration for music (default: 1)
   --music-fade-out <s>   Fade out duration for music (default: 2)
 ${getQualityHelpText()}
+${getViewportHelpText()}
+${getOutputDimensionsHelpText()}
 
   --help, -h             Show this help message
 
@@ -200,6 +203,18 @@ export async function runPipelineCommand(argv) {
   const crf = getFlagValue(args, "--crf");
   const codec = getFlagValue(args, "--codec");
 
+  // Viewport options (for recording)
+  const viewport = getFlagValue(args, "--viewport");
+  const viewportWidth = getFlagValue(args, "--width");
+  const viewportHeight = getFlagValue(args, "--height");
+  const zoom = getFlagValue(args, "--zoom");
+  const deviceScaleFactor = getFlagValue(args, "--device-scale-factor");
+
+  // Output dimension options (for video processing)
+  const outputSize = getFlagValue(args, "--output-size");
+  const outputWidth = getFlagValue(args, "--output-width");
+  const outputHeight = getFlagValue(args, "--output-height");
+
   const rootDir = resolveRoot(root);
   const outputPaths = await getOutputPaths(rootDir, outputDir);
 
@@ -246,6 +261,20 @@ export async function runPipelineCommand(argv) {
       if (crf) console.log(`  - CRF: ${crf}`);
       if (codec) console.log(`  - Codec: ${codec}`);
     }
+    if (viewport || viewportWidth || viewportHeight || zoom || deviceScaleFactor) {
+      console.log("\nViewport options:");
+      if (viewport) console.log(`  - Viewport: ${viewport}`);
+      if (viewportWidth) console.log(`  - Width: ${viewportWidth}`);
+      if (viewportHeight) console.log(`  - Height: ${viewportHeight}`);
+      if (zoom) console.log(`  - Zoom: ${zoom}%`);
+      if (deviceScaleFactor) console.log(`  - Device scale factor: ${deviceScaleFactor}`);
+    }
+    if (outputSize || outputWidth || outputHeight) {
+      console.log("\nOutput dimension options:");
+      if (outputSize) console.log(`  - Output size: ${outputSize}`);
+      if (outputWidth) console.log(`  - Output width: ${outputWidth}`);
+      if (outputHeight) console.log(`  - Output height: ${outputHeight}`);
+    }
     return;
   }
 
@@ -293,8 +322,20 @@ export async function runPipelineCommand(argv) {
     qualityArgs.push("--codec", codec);
   }
 
+  // Build output dimension args to pass through to video processing commands
+  const outputDimensionArgs = [];
+  if (outputSize) {
+    outputDimensionArgs.push("--output-size", outputSize);
+  }
+  if (outputWidth) {
+    outputDimensionArgs.push("--output-width", outputWidth);
+  }
+  if (outputHeight) {
+    outputDimensionArgs.push("--output-height", outputHeight);
+  }
+
   await runStep("split", plan.split, () =>
-    runSplitVideoCommand(["--demo", demoName, ...sharedArgs, ...qualityArgs])
+    runSplitVideoCommand(["--demo", demoName, ...sharedArgs, ...qualityArgs, ...outputDimensionArgs])
   );
 
   const voiceArgs = ["--demo", demoName, ...sharedArgs];
@@ -306,14 +347,14 @@ export async function runPipelineCommand(argv) {
   }
   await runStep("voiceover", plan.voiceover, () => runGenerateVoiceoverCommand(voiceArgs));
 
-  const audioArgs = ["--demo", demoName, ...sharedArgs, ...qualityArgs];
+  const audioArgs = ["--demo", demoName, ...sharedArgs, ...qualityArgs, ...outputDimensionArgs];
   if (padding) {
     audioArgs.push("--padding", padding);
   }
   await runStep("add-audio", plan.addAudio, () => runAddAudioCommand(audioArgs));
 
   // Build concat args with media options and quality settings
-  const concatArgs = ["--demo", demoName, ...sharedArgs, ...qualityArgs];
+  const concatArgs = ["--demo", demoName, ...sharedArgs, ...qualityArgs, ...outputDimensionArgs];
   if (intro) {
     concatArgs.push("--intro", intro);
   }

package/cli/commands/record-demo.js

@@ -15,6 +15,12 @@ import {
   toAbsolute,
 } from "../utils/paths.js";
 import { getMediaDuration } from "../utils/media.js";
+import {
+  parseViewportArgs,
+  parseDeviceScaleFactor,
+  getViewportHelpText,
+  logViewportSettings,
+} from "../utils/dimensions.js";
 
 function printHelp() {
   console.log(`
@@ -35,45 +41,19 @@ Options:
   --root <path>           Project root (defaults to cwd)
   --output-dir <path>     Output directory (defaults to output or e2e/output)
   --storage-state <path>  Playwright storage state JSON
-  --viewport <WxH>        Viewport size, e.g. 1440x900 (default)
-  --width <px>            Viewport width (overrides --viewport)
-  --height <px>           Viewport height (overrides --viewport)
   --headed                Run browser headed
   --slowmo <ms>           Slow down Playwright actions
   --no-video              Skip video recording
   --help, -h              Show this help message
+${getViewportHelpText()}
 
 Examples:
   sceneforge record --definition demo-definitions/create-quote.yaml --base-url http://localhost:5173
   sceneforge record --demo create-quote --definitions-dir examples --base-url http://localhost:5173
+  sceneforge record --demo create-quote --base-url http://localhost:5173 --viewport 1920x1080 --zoom 150
 `);
 }
 
-function parseViewport(args) {
-  const viewportValue = getFlagValue(args, "--viewport");
-  const widthValue = getFlagValue(args, "--width");
-  const heightValue = getFlagValue(args, "--height");
-
-  const defaultViewport = { width: 1440, height: 900 };
-
-  if (widthValue || heightValue) {
-    const width = widthValue ? Number(widthValue) : defaultViewport.width;
-    const height = heightValue ? Number(heightValue) : defaultViewport.height;
-    return { width, height };
-  }
-
-  if (!viewportValue) {
-    return defaultViewport;
-  }
-
-  const match = viewportValue.match(/^(\d+)x(\d+)$/i);
-  if (!match) {
-    return defaultViewport;
-  }
-
-  return { width: Number(match[1]), height: Number(match[2]) };
-}
-
 function resolveStartUrl(startPath, baseUrl) {
   if (!startPath) return null;
   const interpolated = startPath
@@ -233,7 +213,16 @@ export async function runRecordDemoCommand(argv) {
   await ensureDir(outputPaths.outputDir);
   await ensureDir(outputPaths.videosDir);
 
-  const viewport = parseViewport(args);
+  const viewport = parseViewportArgs(args, getFlagValue);
+  const deviceScaleFactor = parseDeviceScaleFactor(args, getFlagValue);
+
+  logViewportSettings(viewport, deviceScaleFactor, "[record]");
+
+  // Calculate video recording size (viewport * scale factor for high-DPI capture)
+  const recordVideoSize = {
+    width: Math.round(viewport.width * deviceScaleFactor),
+    height: Math.round(viewport.height * deviceScaleFactor),
+  };
 
   const recordDir = path.join(outputPaths.videosDir, ".recordings", definition.name);
   if (!noVideo) {
@@ -247,7 +236,8 @@ export async function runRecordDemoCommand(argv) {
 
   const context = await browser.newContext({
     viewport,
-    recordVideo: noVideo ? undefined : { dir: recordDir, size: viewport },
+    deviceScaleFactor,
+    recordVideo: noVideo ? undefined : { dir: recordDir, size: recordVideoSize },
     storageState: storageState ? toAbsolute(rootDir, storageState) : undefined,
     locale: locale || undefined,
     extraHTTPHeaders: locale

package/cli/commands/split-video.js

@@ -10,6 +10,12 @@ import {
   getQualityHelpText,
   logQualitySettings,
 } from "../utils/quality.js";
+import {
+  parseOutputDimensions,
+  getOutputDimensionsHelpText,
+  getScaleFilterArgs,
+  logOutputDimensions,
+} from "../utils/dimensions.js";
 
 function printHelp() {
   console.log(`
@@ -25,11 +31,13 @@ Options:
   --output-dir <path>   Output directory (defaults to e2e/output or output)
   --help, -h            Show this help message
 ${getQualityHelpText()}
+${getOutputDimensionsHelpText()}
 
 Examples:
   sceneforge split --demo create-quote
   sceneforge split --demo create-quote --quality high
   sceneforge split --demo create-quote --crf 15 --codec libx265
+  sceneforge split --demo create-quote --output-size 1080p
   sceneforge split --all
 `);
 }
@@ -63,9 +71,10 @@ async function findVideoFile(demoName, videosDir, testResultsDir) {
   return null;
 }
 
-async function splitDemo(demoName, paths, qualityOptions = {}) {
+async function splitDemo(demoName, paths, qualityOptions = {}, outputDimensions = null) {
   console.log(`\n[split] Processing: ${demoName}\n`);
   logQualitySettings(qualityOptions, "[split]");
+  logOutputDimensions(outputDimensions, "[split]");
 
   const scriptPath = path.join(paths.scriptsDir, `${demoName}.json`);
   let script;
@@ -127,6 +136,7 @@ async function splitDemo(demoName, paths, qualityOptions = {}) {
 
     try {
       const encodingArgs = getVideoEncodingArgs({ ...qualityOptions, includeAudio: false });
+      const scaleArgs = getScaleFilterArgs(outputDimensions);
       await runFFmpeg([
         "-y",
         "-i",
@@ -135,6 +145,7 @@ async function splitDemo(demoName, paths, qualityOptions = {}) {
         String(startSec),
         "-t",
         String(duration),
+        ...scaleArgs,
         ...encodingArgs,
         "-an",
         outputPath,
@@ -181,7 +192,7 @@ async function splitDemo(demoName, paths, qualityOptions = {}) {
   console.log(`[split]   Manifest: ${manifestPath}`);
 }
 
-async function splitAll(paths, qualityOptions = {}) {
+async function splitAll(paths, qualityOptions = {}, outputDimensions = null) {
   console.log("\n[split] Processing all demos...\n");
 
   try {
@@ -199,7 +210,7 @@ async function splitAll(paths, qualityOptions = {}) {
 
     for (const file of scriptFiles) {
       const demoName = path.basename(file, ".json");
-      await splitDemo(demoName, paths, qualityOptions);
+      await splitDemo(demoName, paths, qualityOptions, outputDimensions);
     }
 
     console.log("\n[split] All demos processed!");
@@ -230,14 +241,15 @@ export async function runSplitVideoCommand(argv) {
   const rootDir = resolveRoot(root);
   const paths = await getOutputPaths(rootDir, outputDir);
   const qualityOptions = parseQualityArgs(args, getFlagValue, hasFlag);
+  const outputDimensions = parseOutputDimensions(args, getFlagValue);
 
   if (demo) {
-    await splitDemo(demo, paths, qualityOptions);
+    await splitDemo(demo, paths, qualityOptions, outputDimensions);
     return;
   }
 
   if (all) {
-    await splitAll(paths, qualityOptions);
+    await splitAll(paths, qualityOptions, outputDimensions);
     return;
   }
 

package/cli/utils/dimensions.js

@@ -0,0 +1,249 @@
+/**
+ * Viewport and output dimensions configuration
+ *
+ * Browser Viewport:
+ * - Controls the browser window size during recording
+ * - Supports device scale factor (zoom) for high-DPI capture
+ *
+ * Output Dimensions:
+ * - Controls the final video resolution after processing
+ * - Supports common presets (720p, 1080p, 4k) or custom WxH
+ */
+
+export const VIEWPORT_PRESETS = {
+  "720p": { width: 1280, height: 720 },
+  "1080p": { width: 1920, height: 1080 },
+  "1440p": { width: 2560, height: 1440 },
+  "4k": { width: 3840, height: 2160 },
+};
+
+export const OUTPUT_PRESETS = {
+  // Landscape formats
+  "720p": { width: 1280, height: 720, description: "HD 720p (landscape)" },
+  "1080p": { width: 1920, height: 1080, description: "Full HD 1080p (landscape)" },
+  "1440p": { width: 2560, height: 1440, description: "QHD 1440p (landscape)" },
+  "4k": { width: 3840, height: 2160, description: "4K UHD (landscape)" },
+  // Portrait/vertical formats (for mobile, TikTok, YouTube Shorts, Reels)
+  "720p-portrait": { width: 720, height: 1280, description: "HD 720p (portrait)" },
+  "1080p-portrait": { width: 1080, height: 1920, description: "Full HD 1080p (portrait)" },
+  "tiktok": { width: 1080, height: 1920, description: "TikTok/Reels (1080x1920)" },
+  "shorts": { width: 1080, height: 1920, description: "YouTube Shorts (1080x1920)" },
+  "reels": { width: 1080, height: 1920, description: "Instagram Reels (1080x1920)" },
+  // Square format (Instagram posts)
+  "square": { width: 1080, height: 1080, description: "Square (1080x1080)" },
+  "square-720": { width: 720, height: 720, description: "Square (720x720)" },
+};
+
+export const DEFAULT_VIEWPORT = { width: 1440, height: 900 };
+export const DEFAULT_DEVICE_SCALE_FACTOR = 1;
+
+/**
+ * Parse a dimension string like "1920x1080" or a preset name like "1080p"
+ * @param {string} value - Dimension string or preset name
+ * @param {Object} presets - Presets object to check against
+ * @param {Object} defaultValue - Default dimensions if parsing fails
+ * @returns {Object} { width, height }
+ */
+export function parseDimensions(value, presets, defaultValue) {
+  if (!value) {
+    return defaultValue;
+  }
+
+  // Check if it's a preset name
+  const preset = presets[value.toLowerCase()];
+  if (preset) {
+    return { width: preset.width, height: preset.height };
+  }
+
+  // Try to parse WxH format
+  const match = value.match(/^(\d+)x(\d+)$/i);
+  if (match) {
+    return { width: Number(match[1]), height: Number(match[2]) };
+  }
+
+  return defaultValue;
+}
+
+/**
+ * Parse viewport options from CLI arguments
+ * @param {string[]} args - CLI arguments
+ * @param {Function} getFlagValue - Function to get flag values
+ * @returns {Object} { width, height }
+ */
+export function parseViewportArgs(args, getFlagValue) {
+  const viewportValue = getFlagValue(args, "--viewport");
+  const widthValue = getFlagValue(args, "--width");
+  const heightValue = getFlagValue(args, "--height");
+
+  // Individual width/height override viewport string
+  if (widthValue || heightValue) {
+    const width = widthValue ? Number(widthValue) : DEFAULT_VIEWPORT.width;
+    const height = heightValue ? Number(heightValue) : DEFAULT_VIEWPORT.height;
+    return { width, height };
+  }
+
+  return parseDimensions(viewportValue, VIEWPORT_PRESETS, DEFAULT_VIEWPORT);
+}
+
+/**
+ * Parse device scale factor (zoom) from CLI arguments
+ * @param {string[]} args - CLI arguments
+ * @param {Function} getFlagValue - Function to get flag values
+ * @returns {number} Device scale factor (1 = 100%, 1.5 = 150%, 2 = 200%)
+ */
+export function parseDeviceScaleFactor(args, getFlagValue) {
+  const zoomValue = getFlagValue(args, "--zoom");
+  const scaleValue = getFlagValue(args, "--device-scale-factor");
+
+  // --zoom takes a percentage (100, 150, 200)
+  if (zoomValue !== null && zoomValue !== undefined) {
+    const zoom = Number(zoomValue);
+    if (Number.isFinite(zoom) && zoom > 0) {
+      return zoom / 100; // Convert percentage to scale factor
+    }
+  }
+
+  // --device-scale-factor takes the actual scale (1, 1.5, 2)
+  if (scaleValue !== null && scaleValue !== undefined) {
+    const scale = Number(scaleValue);
+    if (Number.isFinite(scale) && scale > 0) {
+      return scale;
+    }
+  }
+
+  return DEFAULT_DEVICE_SCALE_FACTOR;
+}
+
+/**
+ * Parse output dimensions from CLI arguments
+ * @param {string[]} args - CLI arguments
+ * @param {Function} getFlagValue - Function to get flag values
+ * @returns {Object|null} { width, height } or null if not specified
+ */
+export function parseOutputDimensions(args, getFlagValue) {
+  const outputSize = getFlagValue(args, "--output-size");
+  const outputWidth = getFlagValue(args, "--output-width");
+  const outputHeight = getFlagValue(args, "--output-height");
+
+  // Individual width/height override --output-size
+  if (outputWidth || outputHeight) {
+    // Need both for explicit dimensions, or use -1 for auto-scale
+    const width = outputWidth ? Number(outputWidth) : -1;
+    const height = outputHeight ? Number(outputHeight) : -1;
+    if ((width > 0 || width === -1) && (height > 0 || height === -1)) {
+      return { width, height };
+    }
+  }
+
+  if (!outputSize) {
+    return null; // No scaling, keep original dimensions
+  }
+
+  // Check if it's a preset
+  const preset = OUTPUT_PRESETS[outputSize.toLowerCase()];
+  if (preset) {
+    return { width: preset.width, height: preset.height };
+  }
+
+  // Try to parse WxH format
+  const match = outputSize.match(/^(\d+)x(\d+)$/i);
+  if (match) {
+    return { width: Number(match[1]), height: Number(match[2]) };
+  }
+
+  console.warn(`[warning] Invalid output size "${outputSize}", keeping original dimensions`);
+  return null;
+}
+
+/**
+ * Get FFmpeg scale filter arguments
+ * @param {Object|null} dimensions - { width, height } or null for no scaling
+ *                                   Use -1 for auto-scale maintaining aspect ratio
+ * @returns {string[]} FFmpeg arguments for scaling, or empty array
+ */
+export function getScaleFilterArgs(dimensions) {
+  if (!dimensions) {
+    return [];
+  }
+
+  const { width, height } = dimensions;
+
+  // If either dimension is -1, scale while maintaining aspect ratio (no padding)
+  if (width === -1 || height === -1) {
+    return ["-vf", `scale=${width}:${height}`];
+  }
+
+  // Use scale filter with padding to maintain aspect ratio and fit exact dimensions
+  // scale=W:H:force_original_aspect_ratio=decrease,pad=W:H:(ow-iw)/2:(oh-ih)/2
+  return [
+    "-vf",
+    `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:black`,
+  ];
+}
+
+/**
+ * Get help text for viewport options (recording)
+ * @returns {string}
+ */
+export function getViewportHelpText() {
+  return `
+Viewport Options (Recording):
+  --viewport <WxH|preset>  Browser viewport size (default: 1440x900)
+                           Presets: 720p, 1080p, 1440p, 4k
+                           Example: --viewport 1920x1080 or --viewport 1080p
+  --width <px>             Viewport width (overrides --viewport)
+  --height <px>            Viewport height (overrides --viewport)
+  --zoom <percent>         Browser zoom level: 100, 150, 200 (default: 100)
+  --device-scale-factor <n> Device pixel ratio: 1, 1.5, 2 (alternative to --zoom)`;
+}
+
+/**
+ * Get help text for output dimension options (video processing)
+ * @returns {string}
+ */
+export function getOutputDimensionsHelpText() {
+  return `
+Output Dimensions:
+  --output-size <WxH|preset>  Scale output video to dimensions
+                              Landscape: 720p, 1080p, 1440p, 4k
+                              Portrait:  720p-portrait, 1080p-portrait
+                              Mobile:    tiktok, shorts, reels (1080x1920)
+                              Square:    square (1080x1080), square-720
+                              Custom:    --output-size 1920x1080
+  --output-width <px>         Output width (use with --output-height or -1 for auto)
+  --output-height <px>        Output height (use with --output-width or -1 for auto)
+                              If not specified, keeps original recording dimensions`;
+}
+
+/**
+ * Log viewport settings being used
+ * @param {Object} viewport - { width, height }
+ * @param {number} deviceScaleFactor - Scale factor
+ * @param {string} prefix - Log prefix
+ */
+export function logViewportSettings(viewport, deviceScaleFactor, prefix = "") {
+  const zoomPercent = Math.round(deviceScaleFactor * 100);
+  console.log(
+    `${prefix} Viewport: ${viewport.width}x${viewport.height} @ ${zoomPercent}% zoom`
+  );
+  if (deviceScaleFactor !== 1) {
+    const effectiveRes = {
+      width: Math.round(viewport.width * deviceScaleFactor),
+      height: Math.round(viewport.height * deviceScaleFactor),
+    };
+    console.log(
+      `${prefix} Effective capture resolution: ${effectiveRes.width}x${effectiveRes.height}`
+    );
+  }
+}
+
+/**
+ * Log output dimension settings
+ * @param {Object|null} dimensions - { width, height } or null
+ * @param {string} prefix - Log prefix
+ */
+export function logOutputDimensions(dimensions, prefix = "") {
+  if (dimensions) {
+    console.log(`${prefix} Output size: ${dimensions.width}x${dimensions.height}`);
+  }
+}

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

@@ -25,6 +25,13 @@ sceneforge record --definition <path> [options]
 | `--storage` | Path to storage state JSON |
 | `--slowmo` | Slow down actions by ms |
 | `--env-file` | Path to .env file |
+| `--viewport` | Browser viewport size (preset or WxH, default: 1440x900) |
+| `--width` | Viewport width (overrides --viewport) |
+| `--height` | Viewport height (overrides --viewport) |
+| `--zoom` | Browser zoom level: 100, 150, 200 (default: 100) |
+| `--device-scale-factor` | Device pixel ratio: 1, 1.5, 2 |
+
+**Viewport Presets:** 720p (1280x720), 1080p (1920x1080), 1440p (2560x1440), 4k (3840x2160)
 
 **Examples:**
 ```bash
@@ -36,6 +43,12 @@ sceneforge record -d demo.yaml -b http://localhost:3000 --headed
 
 # With auth state
 sceneforge record -d demo.yaml -b http://localhost:3000 --storage ./auth.json
+
+# Record at 1080p viewport
+sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p
+
+# Record with zoom for extra detail
+sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1920x1080 --zoom 150
 ```
 
 ### setup
@@ -78,6 +91,14 @@ sceneforge pipeline --definition <path> [options]
 | `--skip-voiceover` | Skip voiceover generation |
 | `--skip-concat` | Skip final concatenation |
 | `--resume` | Resume from last successful step |
+| `--quality` | Quality preset: low, medium, high |
+| `--crf` | Override CRF value |
+| `--codec` | Video codec: libx264, libx265 |
+| `--viewport` | Browser viewport size (preset or WxH) |
+| `--zoom` | Browser zoom level: 100, 150, 200 |
+| `--output-size` | Output video dimensions (preset or WxH) |
+| `--output-width` | Output width (-1 for auto) |
+| `--output-height` | Output height (-1 for auto) |
 
 **Examples:**
 ```bash
@@ -89,6 +110,18 @@ sceneforge pipeline -d demo.yaml -b http://localhost:3000 --resume
 
 # Skip recording (use existing videos)
 sceneforge pipeline -d demo.yaml --skip-record
+
+# High quality 1080p output
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --quality high --output-size 1080p
+
+# TikTok/YouTube Shorts format
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --output-size tiktok --quality high
+
+# Full options: viewport + zoom + output scaling
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
+  --viewport 1080p --zoom 150 \
+  --output-size 1080p \
+  --quality high
 ```
 
 ### split
@@ -106,9 +139,14 @@ sceneforge split --demo <name> [options]
 | `--quality` | Quality preset: low, medium, high (default: medium) |
 | `--crf` | Override CRF value (0-51, lower = better) |
 | `--codec` | Video codec: libx264, libx265 (default: libx264) |
+| `--output-size` | Output video dimensions (preset or WxH) |
+| `--output-width` | Output width (-1 for auto) |
+| `--output-height` | Output height (-1 for auto) |
 
 **Video Quality:** Configurable via `--quality` preset or `--crf`/`--codec` flags. Default: medium preset (CRF 18, libx264).
 
+**Output Presets:** 720p, 1080p, 1440p, 4k (landscape), tiktok/shorts/reels (1080x1920 portrait), square (1080x1080)
+
 ### voiceover
 Generate voiceover audio from scripts.
 
@@ -143,9 +181,14 @@ sceneforge add-audio --demo <name> [options]
 | `--quality` | Quality preset: low, medium, high (default: medium) |
 | `--crf` | Override CRF value (0-51, lower = better) |
 | `--codec` | Video codec: libx264, libx265 (default: libx264) |
+| `--output-size` | Output video dimensions (preset or WxH) |
+| `--output-width` | Output width (-1 for auto) |
+| `--output-height` | Output height (-1 for auto) |
 
 **Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Audio: AAC 192kbps.
 
+**Output Presets:** 720p, 1080p, 1440p, 4k (landscape), tiktok/shorts/reels (1080x1920 portrait), square (1080x1080)
+
 ### concat
 Concatenate step clips into final video.
 
@@ -161,6 +204,9 @@ sceneforge concat --demo <name> [options]
 | `--quality` | Quality preset: low, medium, high (default: medium) |
 | `--crf` | Override CRF value (0-51, lower = better) |
 | `--codec` | Video codec: libx264, libx265 (default: libx264) |
+| `--output-size` | Output video dimensions (preset or WxH) |
+| `--output-width` | Output width (-1 for auto) |
+| `--output-height` | Output height (-1 for auto) |
 | `--intro` | Intro video to prepend |
 | `--outro` | Outro video to append |
 | `--music` | Background music file |
@@ -168,6 +214,8 @@ sceneforge concat --demo <name> [options]
 
 **Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Includes `+faststart` for web streaming. Audio: AAC 192kbps.
 
+**Output Presets:** 720p, 1080p, 1440p, 4k (landscape), tiktok/shorts/reels (1080x1920 portrait), square (1080x1080)
+
 ### doctor
 Run environment diagnostics.
 
@@ -314,3 +362,87 @@ sceneforge split --demo my-demo --crf 15
 - 18 = Visually lossless (medium preset, default)
 - 23 = FFmpeg default
 - 28 = Lower quality (low preset)
+
+## Viewport Settings
+
+Control browser viewport size and zoom during recording for high-DPI capture.
+
+### CLI Flags (record, pipeline)
+
+```bash
+--viewport <WxH|preset>      # Browser viewport size (default: 1440x900)
+--width <px>                 # Viewport width (overrides --viewport)
+--height <px>                # Viewport height (overrides --viewport)
+--zoom <percent>             # Browser zoom: 100, 150, 200 (default: 100)
+--device-scale-factor <n>    # Device pixel ratio: 1, 1.5, 2
+```
+
+### Viewport Presets
+
+| Preset | Resolution |
+|--------|------------|
+| `720p` | 1280x720 |
+| `1080p` | 1920x1080 |
+| `1440p` | 2560x1440 |
+| `4k` | 3840x2160 |
+
+### Why Viewport Settings Matter
+
+- Larger viewports capture more UI detail and clarity
+- Zoom (device scale factor) increases effective pixel density
+- A 1080p viewport at 150% zoom captures at 2880x1620 effective pixels
+- Useful for creating videos that look sharp on retina displays
+
+## Output Dimensions
+
+Control final video resolution after processing. Supports landscape, portrait, and square formats.
+
+### CLI Flags (split, add-audio, concat, pipeline)
+
+```bash
+--output-size <WxH|preset>   # Output video dimensions
+--output-width <px>          # Output width (-1 for auto)
+--output-height <px>         # Output height (-1 for auto)
+```
+
+### Output Presets
+
+| Preset | Resolution | Use Case |
+|--------|------------|----------|
+| `720p` | 1280x720 | HD landscape |
+| `1080p` | 1920x1080 | Full HD landscape |
+| `1440p` | 2560x1440 | QHD landscape |
+| `4k` | 3840x2160 | 4K UHD landscape |
+| `720p-portrait` | 720x1280 | HD portrait |
+| `1080p-portrait` | 1080x1920 | Full HD portrait |
+| `tiktok` | 1080x1920 | TikTok/Instagram Reels |
+| `shorts` | 1080x1920 | YouTube Shorts |
+| `reels` | 1080x1920 | Instagram Reels |
+| `square` | 1080x1080 | Square format |
+| `square-720` | 720x720 | Square format (smaller) |
+
+### How Scaling Works
+
+- Videos are scaled while maintaining aspect ratio
+- Black padding (letterboxing/pillarboxing) is added when aspect ratios don't match
+- For portrait formats, landscape recordings will have vertical black bars
+- For auto-scale (`-1`), the dimension is calculated to maintain aspect ratio
+
+### Examples
+
+```bash
+# Standard 1080p output
+sceneforge concat --demo my-demo --output-size 1080p
+
+# TikTok/YouTube Shorts (portrait)
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --output-size tiktok
+
+# Square for Instagram
+sceneforge concat --demo my-demo --output-size square
+
+# Full pipeline with all options
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
+  --viewport 1080p --zoom 150 \
+  --output-size 1080p \
+  --quality high
+```

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

@@ -25,6 +25,13 @@ sceneforge record --definition <path> [options]
 | `--storage` | Path to storage state JSON |
 | `--slowmo` | Slow down actions by ms |
 | `--env-file` | Path to .env file |
+| `--viewport` | Browser viewport size (preset or WxH, default: 1440x900) |
+| `--width` | Viewport width (overrides --viewport) |
+| `--height` | Viewport height (overrides --viewport) |
+| `--zoom` | Browser zoom level: 100, 150, 200 (default: 100) |
+| `--device-scale-factor` | Device pixel ratio: 1, 1.5, 2 |
+
+**Viewport Presets:** 720p (1280x720), 1080p (1920x1080), 1440p (2560x1440), 4k (3840x2160)
 
 **Examples:**
 ```bash
@@ -36,6 +43,12 @@ sceneforge record -d demo.yaml -b http://localhost:3000 --headed
 
 # With auth state
 sceneforge record -d demo.yaml -b http://localhost:3000 --storage ./auth.json
+
+# Record at 1080p viewport
+sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p
+
+# Record with zoom for extra detail
+sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1920x1080 --zoom 150
 ```
 
 ### setup
@@ -78,6 +91,14 @@ sceneforge pipeline --definition <path> [options]
 | `--skip-voiceover` | Skip voiceover generation |
 | `--skip-concat` | Skip final concatenation |
 | `--resume` | Resume from last successful step |
+| `--quality` | Quality preset: low, medium, high |
+| `--crf` | Override CRF value |
+| `--codec` | Video codec: libx264, libx265 |
+| `--viewport` | Browser viewport size (preset or WxH) |
+| `--zoom` | Browser zoom level: 100, 150, 200 |
+| `--output-size` | Output video dimensions (preset or WxH) |
+| `--output-width` | Output width (-1 for auto) |
+| `--output-height` | Output height (-1 for auto) |
 
 **Examples:**
 ```bash
@@ -89,6 +110,18 @@ sceneforge pipeline -d demo.yaml -b http://localhost:3000 --resume
 
 # Skip recording (use existing videos)
 sceneforge pipeline -d demo.yaml --skip-record
+
+# High quality 1080p output
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --quality high --output-size 1080p
+
+# TikTok/YouTube Shorts format
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --output-size tiktok --quality high
+
+# Full options: viewport + zoom + output scaling
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
+  --viewport 1080p --zoom 150 \
+  --output-size 1080p \
+  --quality high
 ```
 
 ### split
@@ -106,9 +139,14 @@ sceneforge split --demo <name> [options]
 | `--quality` | Quality preset: low, medium, high (default: medium) |
 | `--crf` | Override CRF value (0-51, lower = better) |
 | `--codec` | Video codec: libx264, libx265 (default: libx264) |
+| `--output-size` | Output video dimensions (preset or WxH) |
+| `--output-width` | Output width (-1 for auto) |
+| `--output-height` | Output height (-1 for auto) |
 
 **Video Quality:** Configurable via `--quality` preset or `--crf`/`--codec` flags. Default: medium preset (CRF 18, libx264).
 
+**Output Presets:** 720p, 1080p, 1440p, 4k (landscape), tiktok/shorts/reels (1080x1920 portrait), square (1080x1080)
+
 ### voiceover
 Generate voiceover audio from scripts.
 
@@ -143,9 +181,14 @@ sceneforge add-audio --demo <name> [options]
 | `--quality` | Quality preset: low, medium, high (default: medium) |
 | `--crf` | Override CRF value (0-51, lower = better) |
 | `--codec` | Video codec: libx264, libx265 (default: libx264) |
+| `--output-size` | Output video dimensions (preset or WxH) |
+| `--output-width` | Output width (-1 for auto) |
+| `--output-height` | Output height (-1 for auto) |
 
 **Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Audio: AAC 192kbps.
 
+**Output Presets:** 720p, 1080p, 1440p, 4k (landscape), tiktok/shorts/reels (1080x1920 portrait), square (1080x1080)
+
 ### concat
 Concatenate step clips into final video.
 
@@ -161,6 +204,9 @@ sceneforge concat --demo <name> [options]
 | `--quality` | Quality preset: low, medium, high (default: medium) |
 | `--crf` | Override CRF value (0-51, lower = better) |
 | `--codec` | Video codec: libx264, libx265 (default: libx264) |
+| `--output-size` | Output video dimensions (preset or WxH) |
+| `--output-width` | Output width (-1 for auto) |
+| `--output-height` | Output height (-1 for auto) |
 | `--intro` | Intro video to prepend |
 | `--outro` | Outro video to append |
 | `--music` | Background music file |
@@ -168,6 +214,8 @@ sceneforge concat --demo <name> [options]
 
 **Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Includes `+faststart` for web streaming. Audio: AAC 192kbps.
 
+**Output Presets:** 720p, 1080p, 1440p, 4k (landscape), tiktok/shorts/reels (1080x1920 portrait), square (1080x1080)
+
 ### doctor
 Run environment diagnostics.
 
@@ -314,3 +362,87 @@ sceneforge split --demo my-demo --crf 15
 - 18 = Visually lossless (medium preset, default)
 - 23 = FFmpeg default
 - 28 = Lower quality (low preset)
+
+## Viewport Settings
+
+Control browser viewport size and zoom during recording for high-DPI capture.
+
+### CLI Flags (record, pipeline)
+
+```bash
+--viewport <WxH|preset>      # Browser viewport size (default: 1440x900)
+--width <px>                 # Viewport width (overrides --viewport)
+--height <px>                # Viewport height (overrides --viewport)
+--zoom <percent>             # Browser zoom: 100, 150, 200 (default: 100)
+--device-scale-factor <n>    # Device pixel ratio: 1, 1.5, 2
+```
+
+### Viewport Presets
+
+| Preset | Resolution |
+|--------|------------|
+| `720p` | 1280x720 |
+| `1080p` | 1920x1080 |
+| `1440p` | 2560x1440 |
+| `4k` | 3840x2160 |
+
+### Why Viewport Settings Matter
+
+- Larger viewports capture more UI detail and clarity
+- Zoom (device scale factor) increases effective pixel density
+- A 1080p viewport at 150% zoom captures at 2880x1620 effective pixels
+- Useful for creating videos that look sharp on retina displays
+
+## Output Dimensions
+
+Control final video resolution after processing. Supports landscape, portrait, and square formats.
+
+### CLI Flags (split, add-audio, concat, pipeline)
+
+```bash
+--output-size <WxH|preset>   # Output video dimensions
+--output-width <px>          # Output width (-1 for auto)
+--output-height <px>         # Output height (-1 for auto)
+```
+
+### Output Presets
+
+| Preset | Resolution | Use Case |
+|--------|------------|----------|
+| `720p` | 1280x720 | HD landscape |
+| `1080p` | 1920x1080 | Full HD landscape |
+| `1440p` | 2560x1440 | QHD landscape |
+| `4k` | 3840x2160 | 4K UHD landscape |
+| `720p-portrait` | 720x1280 | HD portrait |
+| `1080p-portrait` | 1080x1920 | Full HD portrait |
+| `tiktok` | 1080x1920 | TikTok/Instagram Reels |
+| `shorts` | 1080x1920 | YouTube Shorts |
+| `reels` | 1080x1920 | Instagram Reels |
+| `square` | 1080x1080 | Square format |
+| `square-720` | 720x720 | Square format (smaller) |
+
+### How Scaling Works
+
+- Videos are scaled while maintaining aspect ratio
+- Black padding (letterboxing/pillarboxing) is added when aspect ratios don't match
+- For portrait formats, landscape recordings will have vertical black bars
+- For auto-scale (`-1`), the dimension is calculated to maintain aspect ratio
+
+### Examples
+
+```bash
+# Standard 1080p output
+sceneforge concat --demo my-demo --output-size 1080p
+
+# TikTok/YouTube Shorts (portrait)
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --output-size tiktok
+
+# Square for Instagram
+sceneforge concat --demo my-demo --output-size square
+
+# Full pipeline with all options
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
+  --viewport 1080p --zoom 150 \
+  --output-size 1080p \
+  --quality high
+```

package/package.json

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