simple-ffmpegjs 0.4.0 → 0.4.1

package/README.md

@@ -24,14 +24,14 @@
 - [API Reference](#api-reference)
   - [Constructor](#constructor)
   - [Methods](#methods)
-  - [Clip Types](#clip-types)
+  - [Auto-Sequencing & Duration Shorthand](#auto-sequencing--duration-shorthand)
+  - [Clip Types](#clip-types) — Video, Image, Color, Effect, Text, Subtitle, Audio, Background Music
   - [Platform Presets](#platform-presets)
   - [Watermarks](#watermarks)
   - [Progress Information](#progress-information)
   - [Logging](#logging)
   - [Error Handling](#error-handling)
   - [Cancellation](#cancellation)
-  - [Color Clips](#color-clips)
 - [Examples](#examples)
   - [Clips & Transitions](#clips--transitions)
   - [Text & Animations](#text--animations)
@@ -66,19 +66,26 @@ _Click to watch a "Wonders of the World" video created with simple-ffmpeg — co
 
 ## Features
 
+**Video & Images**
 - **Video Concatenation** — Join multiple clips with optional xfade transitions
+- **Image Support** — Ken Burns effects (zoom, pan) for static images
+- **Color Clips** — Flat colors and gradients (linear, radial) as first-class timeline clips with full transition support
+
+**Audio**
 - **Audio Mixing** — Layer audio tracks, voiceovers, and background music
+
+**Overlays & Effects**
 - **Text Overlays** — Static, word-by-word, and cumulative text with animations
 - **Text Animations** — Typewriter, scale-in, pulse, fade effects
 - **Karaoke Mode** — Word-by-word highlighting with customizable colors
 - **Subtitle Import** — Load SRT, VTT, ASS/SSA subtitle files
 - **Watermarks** — Text or image overlays with positioning and timing control
+- **Effect Clips** — Timed overlay effects (vignette, film grain, blur, color adjust, sepia, black & white, sharpen, chromatic aberration, letterbox) with fade-in/out envelopes
+
+**Developer Experience**
 - **Platform Presets** — Quick configuration for TikTok, YouTube, Instagram, etc.
-- **Image Support** — Ken Burns effects (zoom, pan) for static images
 - **Progress Tracking** — Real-time export progress callbacks
 - **Cancellation** — AbortController support for stopping exports
-- **Color Clips** — Flat colors and gradients (linear, radial) as first-class timeline clips with full transition support
-- **Effect Clips** — Timed overlay effects (vignette, film grain, gaussian blur, color adjustment) with fade-in/out envelopes
 - **Auto-Batching** — Automatically splits complex filter graphs to avoid OS command limits
 - **Schema Export** — Generate a structured description of the clip format for documentation, code generation, or AI context
 - **Pre-Validation** — Validate clip configurations before processing with structured, machine-readable error codes
@@ -249,7 +256,7 @@ Available modules:
 | `audio`    | Standalone audio clips                                      |
 | `image`    | Image clips, Ken Burns effects                              |
 | `color`    | Color clips — flat colors, linear/radial gradients          |
-| `effect`   | Overlay adjustment effects — vignette, grain, blur, grading |
+| `effect`   | Overlay adjustment effects — vignette, grain, blur, color adjust, sepia, B&W, sharpen, chromatic aberration, letterbox |
 | `text`     | Text overlays — all modes, animations, positioning, styling |
 | `subtitle` | Subtitle file import (SRT, VTT, ASS, SSA)                   |
 | `music`    | Background music / background audio, looping                |
@@ -288,9 +295,27 @@ new SIMPLEFFMPEG(options?: {
   fps?: number;             // Frame rate (default: 30)
   validationMode?: 'warn' | 'strict';  // Validation behavior (default: 'warn')
   preset?: string;          // Platform preset (e.g., 'tiktok', 'youtube', 'instagram-post')
+  fontFile?: string;        // Default font file for all text clips (individual clips can override)
 })
 ```
 
+When `fontFile` is set at the project level, every text clip (including karaoke) inherits it automatically. You can still override it on any individual clip:
+
+```js
+const project = new SIMPLEFFMPEG({
+  preset: "tiktok",
+  fontFile: "./fonts/Montserrat-Bold.ttf",   // applies to all text clips
+});
+
+await project.load([
+  { type: "video", url: "intro.mp4", position: 0, end: 10 },
+  // Uses the global font
+  { type: "text", text: "Hello!", position: 1, end: 4, fontSize: 72 },
+  // Overrides with a different font
+  { type: "text", text: "Special", position: 5, end: 8, fontFile: "./fonts/Italic.otf" },
+]);
+```
+
 ### Methods
 
 #### `project.load(clips)`
@@ -320,43 +345,6 @@ SIMPLEFFMPEG.getDuration(clips); // 14.5
 
 Useful for computing text overlay timings or background music end times before calling `load()`.
 
-**Duration and Auto-Sequencing:**
-
-For video, image, and audio clips, you can use shorthand to avoid specifying explicit `position` and `end` values:
-
-- **`duration`** — Use instead of `end`. The library computes `end = position + duration`. You cannot specify both `duration` and `end` on the same clip.
-- **Omit `position`** — The clip is placed immediately after the previous clip on its track. Video and image clips share the visual track; audio clips have their own track. The first clip defaults to `position: 0`.
-
-These can be combined:
-
-```ts
-// Before: manual position/end for every clip
-await project.load([
-  { type: "video", url: "./a.mp4", position: 0, end: 5 },
-  { type: "video", url: "./b.mp4", position: 5, end: 10 },
-  { type: "video", url: "./c.mp4", position: 10, end: 18, cutFrom: 3 },
-]);
-
-// After: auto-sequencing + duration
-await project.load([
-  { type: "video", url: "./a.mp4", duration: 5 },
-  { type: "video", url: "./b.mp4", duration: 5 },
-  { type: "video", url: "./c.mp4", duration: 8, cutFrom: 3 },
-]);
-```
-
-You can mix explicit and implicit positioning freely. Clips with explicit `position` are placed there; subsequent auto-sequenced clips follow from the last clip's end:
-
-```ts
-await project.load([
-  { type: "video", url: "./a.mp4", duration: 5 }, // position: 0, end: 5
-  { type: "video", url: "./b.mp4", position: 10, end: 15 }, // explicit gap
-  { type: "video", url: "./c.mp4", duration: 5 }, // position: 15, end: 20
-]);
-```
-
-Text clips always require an explicit `position` (they're overlays on specific moments). Background music and subtitle clips already have optional `position`/`end` with their own defaults.
-
 #### `SIMPLEFFMPEG.probe(filePath)`
 
 Probe a media file and return comprehensive metadata using ffprobe. Works with video, audio, and image files.
@@ -482,6 +470,43 @@ await project.preview(options?: ExportOptions): Promise<{
 }>
 ```
 
+### Auto-Sequencing & Duration Shorthand
+
+For video, image, and audio clips, you can use shorthand to avoid specifying explicit `position` and `end` values:
+
+- **`duration`** — Use instead of `end`. The library computes `end = position + duration`. You cannot specify both `duration` and `end` on the same clip.
+- **Omit `position`** — The clip is placed immediately after the previous clip on its track. Video and image clips share the visual track; audio clips have their own track. The first clip defaults to `position: 0`.
+
+These can be combined:
+
+```ts
+// Before: manual position/end for every clip
+await project.load([
+  { type: "video", url: "./a.mp4", position: 0, end: 5 },
+  { type: "video", url: "./b.mp4", position: 5, end: 10 },
+  { type: "video", url: "./c.mp4", position: 10, end: 18, cutFrom: 3 },
+]);
+
+// After: auto-sequencing + duration
+await project.load([
+  { type: "video", url: "./a.mp4", duration: 5 },
+  { type: "video", url: "./b.mp4", duration: 5 },
+  { type: "video", url: "./c.mp4", duration: 8, cutFrom: 3 },
+]);
+```
+
+You can mix explicit and implicit positioning freely. Clips with explicit `position` are placed there; subsequent auto-sequenced clips follow from the last clip's end:
+
+```ts
+await project.load([
+  { type: "video", url: "./a.mp4", duration: 5 }, // position: 0, end: 5
+  { type: "video", url: "./b.mp4", position: 10, end: 15 }, // explicit gap
+  { type: "video", url: "./c.mp4", duration: 5 }, // position: 15, end: 20
+]);
+```
+
+Text clips always require an explicit `position` (they're overlays on specific moments). Background music and subtitle clips already have optional `position`/`end` with their own defaults.
+
 ### Clip Types
 
 #### Video Clip
@@ -504,47 +529,6 @@ await project.preview(options?: ExportOptions): Promise<{
 
 All [xfade transitions](https://trac.ffmpeg.org/wiki/Xfade) are supported.
 
-#### Audio Clip
-
-```ts
-{
-  type: "audio";
-  url: string;
-  position?: number;        // Omit to auto-sequence after previous audio clip
-  end?: number;             // Use end OR duration, not both
-  duration?: number;        // Duration in seconds (alternative to end)
-  cutFrom?: number;
-  volume?: number;
-}
-```
-
-#### Background Music
-
-```ts
-{
-  type: "music";            // or "backgroundAudio"
-  url: string;
-  position?: number;        // default: 0
-  end?: number;             // default: project duration
-  cutFrom?: number;
-  volume?: number;          // default: 0.2
-  loop?: boolean;           // Loop audio to fill video duration
-}
-```
-
-Background music is mixed after transitions, so video crossfades won't affect its volume.
-
-**Looping Music:**
-
-If your music track is shorter than your video, enable looping:
-
-```ts
-await project.load([
-  { type: "video", url: "./video.mp4", position: 0, end: 120 },
-  { type: "music", url: "./30s-track.mp3", volume: 0.3, loop: true },
-]);
-```
-
 #### Image Clip
 
 ```ts
@@ -575,6 +559,8 @@ await project.load([
 
 #### Color Clip
 
+Color clips add flat colors or gradients as first-class visual elements. They support transitions, text overlays, and all the same timeline features as video and image clips. Use them for intros, outros, title cards, or anywhere you need a background.
+
 ```ts
 {
   type: "color";
@@ -593,6 +579,73 @@ await project.load([
 }
 ```
 
+`color` accepts any valid FFmpeg color name or hex code:
+
+```ts
+{ type: "color", color: "navy", position: 0, end: 3 }
+{ type: "color", color: "#1a1a2e", position: 0, end: 3 }
+```
+
+**Gradients:**
+
+```ts
+// Linear gradient (vertical by default)
+{
+  type: "color",
+  color: { type: "linear-gradient", colors: ["#0a0a2e", "#4a148c"] },
+  position: 0,
+  end: 4,
+}
+
+// Horizontal linear gradient
+{
+  type: "color",
+  color: { type: "linear-gradient", colors: ["#e74c3c", "#f1c40f", "#2ecc71"], direction: "horizontal" },
+  position: 0,
+  end: 4,
+}
+
+// Radial gradient
+{
+  type: "color",
+  color: { type: "radial-gradient", colors: ["#ff8c00", "#1a0000"] },
+  position: 0,
+  end: 3,
+}
+```
+
+**With transitions:**
+
+```ts
+await project.load([
+  { type: "color", color: "black", position: 0, end: 3 },
+  {
+    type: "video",
+    url: "./main.mp4",
+    position: 3,
+    end: 8,
+    transition: { type: "fade", duration: 0.5 },
+  },
+  {
+    type: "color",
+    color: { type: "radial-gradient", colors: ["#2c3e50", "#000000"] },
+    position: 8,
+    end: 11,
+    transition: { type: "fade", duration: 0.5 },
+  },
+  {
+    type: "text",
+    text: "The End",
+    position: 8.5,
+    end: 10.5,
+    fontSize: 64,
+    fontColor: "white",
+  },
+]);
+```
+
+> **Note:** Timeline gaps (periods with no visual content) always produce a validation error. If a gap is intentional, fill it with a `type: "color"` clip or adjust your clip positions to close the gap.
+
 #### Effect Clip
 
 Effects are overlay adjustment layers. They apply to the already-composed video
@@ -601,34 +654,30 @@ for a time window, and can ramp in/out smoothly (instead of appearing instantly)
 ```ts
 {
   type: "effect";
-  effect: "vignette" | "filmGrain" | "gaussianBlur" | "colorAdjust";
+  effect: EffectName;         // See table below
   position: number;           // Required timeline start (seconds)
   end?: number;               // Use end OR duration, not both
   duration?: number;          // Duration in seconds (alternative to end)
   fadeIn?: number;            // Optional smooth ramp-in (seconds)
   fadeOut?: number;           // Optional smooth ramp-out (seconds)
-  easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out"; // default: "linear"
-  params: {
-    amount?: number;          // Blend amount 0..1 (default: 1)
-
-    // vignette
-    angle?: number;           // radians
-
-    // filmGrain
-    temporal?: boolean;       // default: true
-
-    // gaussianBlur
-    sigma?: number;
-
-    // colorAdjust
-    brightness?: number;      // -1..1
-    contrast?: number;        // 0..3
-    saturation?: number;      // 0..3
-    gamma?: number;           // 0.1..10
-  };
+  params: EffectParams;       // Effect-specific parameters (see table below)
 }
 ```
 
+All effects accept `params.amount` (0-1, default 1) to control the blend intensity. Additional per-effect parameters:
+
+| Effect | Description | Extra Params |
+|---|---|---|
+| `vignette` | Darkened edges | `angle`: radians (default: PI/5) |
+| `filmGrain` | Noise overlay | `strength`: noise intensity 0-1 (default: 0.35), `temporal`: boolean (default: true) |
+| `gaussianBlur` | Gaussian blur | `sigma`: blur radius (default derived from amount) |
+| `colorAdjust` | Color grading | `brightness`: -1..1, `contrast`: 0..3, `saturation`: 0..3, `gamma`: 0.1..10 |
+| `sepia` | Warm vintage tone | — |
+| `blackAndWhite` | Desaturate to grayscale | `contrast`: boost 0-3 (default: 1) |
+| `sharpen` | Sharpen detail | `strength`: unsharp amount 0-3 (default: 1) |
+| `chromaticAberration` | RGB channel split | `shift`: pixel offset 0-20 (default: 4) |
+| `letterbox` | Cinematic bars | `size`: bar height as fraction of frame 0-0.5 (default: 0.12), `color`: string (default: "black") |
+
 #### Text Clip
 
 ```ts
@@ -698,6 +747,47 @@ Import external subtitle files (SRT, VTT, ASS/SSA):
 }
 ```
 
+#### Audio Clip
+
+```ts
+{
+  type: "audio";
+  url: string;
+  position?: number;        // Omit to auto-sequence after previous audio clip
+  end?: number;             // Use end OR duration, not both
+  duration?: number;        // Duration in seconds (alternative to end)
+  cutFrom?: number;
+  volume?: number;
+}
+```
+
+#### Background Music
+
+```ts
+{
+  type: "music";            // or "backgroundAudio"
+  url: string;
+  position?: number;        // default: 0
+  end?: number;             // default: project duration
+  cutFrom?: number;
+  volume?: number;          // default: 0.2
+  loop?: boolean;           // Loop audio to fill video duration
+}
+```
+
+Background music is mixed after transitions, so video crossfades won't affect its volume.
+
+**Looping Music:**
+
+If your music track is shorter than your video, enable looping:
+
+```ts
+await project.load([
+  { type: "video", url: "./video.mp4", position: 0, end: 120 },
+  { type: "music", url: "./30s-track.mp3", volume: 0.3, loop: true },
+]);
+```
+
 ### Platform Presets
 
 Use platform presets to quickly configure optimal dimensions for social media:
@@ -910,90 +1000,6 @@ try {
 }
 ```
 
-### Color Clips
-
-Color clips let you add flat colors or gradients as first-class visual elements in your timeline. They support transitions, text overlays, and all the same timeline features as video and image clips. Use them for intros, outros, title cards, or anywhere you need a background:
-
-**Flat color:**
-
-```ts
-await project.load([
-  // Black intro screen for 2 seconds
-  { type: "color", color: "black", position: 0, end: 2 },
-  // Video starts at 2s
-  { type: "video", url: "./clip.mp4", position: 2, end: 7 },
-]);
-```
-
-`color` accepts any valid FFmpeg color name or hex code:
-
-```ts
-{ type: "color", color: "navy", position: 0, end: 3 }
-{ type: "color", color: "#1a1a2e", position: 0, end: 3 }
-```
-
-**Gradients:**
-
-```ts
-// Linear gradient (vertical by default)
-{
-  type: "color",
-  color: { type: "linear-gradient", colors: ["#0a0a2e", "#4a148c"] },
-  position: 0,
-  end: 4,
-}
-
-// Horizontal linear gradient
-{
-  type: "color",
-  color: { type: "linear-gradient", colors: ["#e74c3c", "#f1c40f", "#2ecc71"], direction: "horizontal" },
-  position: 0,
-  end: 4,
-}
-
-// Radial gradient
-{
-  type: "color",
-  color: { type: "radial-gradient", colors: ["#ff8c00", "#1a0000"] },
-  position: 0,
-  end: 3,
-}
-```
-
-**With transitions:**
-
-Color clips support the same `transition` property as video and image clips:
-
-```ts
-await project.load([
-  { type: "color", color: "black", position: 0, end: 3 },
-  {
-    type: "video",
-    url: "./main.mp4",
-    position: 3,
-    end: 8,
-    transition: { type: "fade", duration: 0.5 },
-  },
-  {
-    type: "color",
-    color: { type: "radial-gradient", colors: ["#2c3e50", "#000000"] },
-    position: 8,
-    end: 11,
-    transition: { type: "fade", duration: 0.5 },
-  },
-  {
-    type: "text",
-    text: "The End",
-    position: 8.5,
-    end: 10.5,
-    fontSize: 64,
-    fontColor: "white",
-  },
-]);
-```
-
-> **Note:** Timeline gaps (periods with no visual content) always produce a validation error. If a gap is intentional, fill it with a `type: "color"` clip or adjust your clip positions to close the gap.
-
 ## Examples
 
 ### Clips & Transitions
@@ -1055,7 +1061,7 @@ await project.load([
 ]);
 ```
 
-When `position` is omitted, clips are placed sequentially — each one starts where the previous one ended. `duration` is an alternative to `end`: the library computes `end = position + duration`. The explicit form (`position: 0, end: 3`) still works identically.
+When `position` is omitted, clips are placed sequentially — see [Auto-Sequencing & Duration Shorthand](#auto-sequencing--duration-shorthand) for details.
 
 > **Note:** Ken Burns effects work best with images at least as large as your output resolution. Smaller images are automatically upscaled (with a validation warning). Use `strictKenBurns: true` in validation options to enforce size requirements instead.
 > If you pass `width`/`height`, they override probed dimensions (useful for remote or generated images).
@@ -1533,7 +1539,7 @@ Available demo scripts (can also be run individually):
 | Script                          | What it tests                                                                          |
 | ------------------------------- | -------------------------------------------------------------------------------------- |
 | `demo-color-clips.js`           | Flat colors, linear/radial gradients, transitions, full composition with color clips   |
-| `demo-effects-pack-1.js`        | Timed overlay effects (vignette, grain, blur, color adjustment) with smooth ramps      |
+| `demo-effects.js`               | Timed overlay effects (all 9 effects) with smooth fade ramps                           |
 | `demo-transitions.js`           | Fade, wipe, slide, dissolve, fadeblack/white, short/long durations, image transitions  |
 | `demo-text-and-animations.js`   | Positioning, fade, pop, pop-bounce, typewriter, scale-in, pulse, styling, word-replace |
 | `demo-ken-burns.js`             | All 6 presets, smart anchors, custom diagonal, slideshow with transitions              |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-ffmpegjs",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Declarative video composition for Node.js — define clips, transitions, text, and audio as simple objects, and let FFmpeg handle the rest.",
   "author": "Brayden Blackwell <braydenblackwell21@gmail.com> (https://github.com/Fats403)",
   "license": "MIT",

package/src/core/validation.js

@@ -106,8 +106,17 @@ function createIssue(code, path, message, received = undefined) {
   return issue;
 }
 
-const EFFECT_TYPES = ["vignette", "filmGrain", "gaussianBlur", "colorAdjust"];
-const EFFECT_EASING = ["linear", "ease-in", "ease-out", "ease-in-out"];
+const EFFECT_TYPES = [
+  "vignette",
+  "filmGrain",
+  "gaussianBlur",
+  "colorAdjust",
+  "sepia",
+  "blackAndWhite",
+  "sharpen",
+  "chromaticAberration",
+  "letterbox",
+];
 
 function validateFiniteNumber(value, path, errors, opts = {}) {
   const { min = null, max = null, minInclusive = true, maxInclusive = true } = opts;
@@ -169,17 +178,6 @@ function validateEffectClip(clip, path, errors) {
   if (clip.fadeOut != null) {
     validateFiniteNumber(clip.fadeOut, `${path}.fadeOut`, errors, { min: 0 });
   }
-  if (clip.easing != null && !EFFECT_EASING.includes(clip.easing)) {
-    errors.push(
-      createIssue(
-        ValidationCodes.INVALID_VALUE,
-        `${path}.easing`,
-        `Invalid easing '${clip.easing}'. Expected: ${EFFECT_EASING.join(", ")}`,
-        clip.easing
-      )
-    );
-  }
-
   if (typeof clip.position === "number" && typeof clip.end === "number") {
     const duration = clip.end - clip.position;
     const fadeTotal = (clip.fadeIn || 0) + (clip.fadeOut || 0);
@@ -227,6 +225,12 @@ function validateEffectClip(clip, path, errors) {
       });
     }
   } else if (clip.effect === "filmGrain") {
+    if (params.strength != null) {
+      validateFiniteNumber(params.strength, `${path}.params.strength`, errors, {
+        min: 0,
+        max: 1,
+      });
+    }
     if (params.temporal != null && typeof params.temporal !== "boolean") {
       errors.push(
         createIssue(
@@ -269,6 +273,46 @@ function validateEffectClip(clip, path, errors) {
         max: 10,
       });
     }
+  } else if (clip.effect === "sepia") {
+    // sepia only uses amount (base param) — no extra params to validate
+  } else if (clip.effect === "blackAndWhite") {
+    if (params.contrast != null) {
+      validateFiniteNumber(params.contrast, `${path}.params.contrast`, errors, {
+        min: 0,
+        max: 3,
+      });
+    }
+  } else if (clip.effect === "sharpen") {
+    if (params.strength != null) {
+      validateFiniteNumber(params.strength, `${path}.params.strength`, errors, {
+        min: 0,
+        max: 3,
+      });
+    }
+  } else if (clip.effect === "chromaticAberration") {
+    if (params.shift != null) {
+      validateFiniteNumber(params.shift, `${path}.params.shift`, errors, {
+        min: 0,
+        max: 20,
+      });
+    }
+  } else if (clip.effect === "letterbox") {
+    if (params.size != null) {
+      validateFiniteNumber(params.size, `${path}.params.size`, errors, {
+        min: 0,
+        max: 0.5,
+      });
+    }
+    if (params.color != null && typeof params.color !== "string") {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_VALUE,
+          `${path}.params.color`,
+          "color must be a string",
+          params.color
+        )
+      );
+    }
   }
 }
 

package/src/ffmpeg/bgm_builder.js

@@ -43,15 +43,31 @@ function buildBackgroundMusicMix(
     const adelay = effectivePosition * 1000;
     const trimEnd = effectiveCutFrom + (effectiveEnd - effectivePosition);
     const outLabel = `[bg${i}]`;
-    filter += `[${inputIndex}:a]volume=${effectiveVolume},atrim=start=${effectiveCutFrom}:end=${trimEnd},adelay=${adelay}|${adelay},asetpts=PTS-STARTPTS${outLabel};`;
+    filter += `[${inputIndex}:a]volume=${effectiveVolume},atrim=start=${effectiveCutFrom}:end=${trimEnd},asetpts=PTS-STARTPTS,adelay=${adelay}|${adelay}${outLabel};`;
     bgLabels.push(outLabel);
   });
 
   if (bgLabels.length > 0) {
     if (existingAudioLabel) {
-      filter += `${existingAudioLabel}${bgLabels.join("")}amix=inputs=${
-        bgLabels.length + 1
-      }:duration=longest[finalaudio];`;
+      // Generate a silence anchor from time 0 so that amix starts producing
+      // output immediately. Without this, amix waits for ALL inputs to have
+      // frames before outputting — if the existing audio (e.g. delayed video
+      // audio) starts later on the timeline, background music is silenced
+      // until that point.
+      const anchorDur = Math.max(projectDuration, visualEnd || 0, 0.1);
+      const padLabel = "[_bgmpad]";
+      filter += `anullsrc=cl=stereo,atrim=end=${anchorDur}${padLabel};`;
+
+      // Use normalize=0 with explicit weights so the silence anchor
+      // contributes no audio energy while preserving the same volume
+      // balance as a direct amix of the real inputs.
+      const realCount = bgLabels.length + 1; // bgm tracks + existing audio
+      const w = (1 / realCount).toFixed(6);
+      const weights = ["0", ...Array(realCount).fill(w)].join(" ");
+
+      filter += `${padLabel}${existingAudioLabel}${bgLabels.join("")}amix=inputs=${
+        bgLabels.length + 2
+      }:duration=longest:weights='${weights}':normalize=0[finalaudio];`;
       return { filter, finalAudioLabel: "[finalaudio]", hasAudio: true };
     }
     filter += `${bgLabels.join("")}amix=inputs=${

package/src/ffmpeg/effect_builder.js

@@ -24,11 +24,14 @@ function buildProcessedEffectFilter(effectClip, inputLabel, outputLabel) {
   }
 
   if (effectClip.effect === "filmGrain") {
-    const grainStrength = clamp(
-      (typeof params.amount === "number" ? params.amount : 0.35) * 100,
+    // `strength` controls noise intensity (0-1, default 0.35).
+    // `amount` is used purely for overlay blend alpha.
+    const strength = clamp(
+      typeof params.strength === "number" ? params.strength : 0.35,
       0,
-      100
+      1
     );
+    const grainStrength = strength * 100;
     const flags = params.temporal === false ? "u" : "t+u";
     return {
       filter: `${inputLabel}noise=alls=${formatNumber(
@@ -53,24 +56,103 @@ function buildProcessedEffectFilter(effectClip, inputLabel, outputLabel) {
     };
   }
 
-  // colorAdjust
-  const brightness =
-    typeof params.brightness === "number" ? params.brightness : 0;
-  const contrast = typeof params.contrast === "number" ? params.contrast : 1;
-  const saturation =
-    typeof params.saturation === "number" ? params.saturation : 1;
-  const gamma = typeof params.gamma === "number" ? params.gamma : 1;
-
-  return {
-    filter:
-      `${inputLabel}eq=` +
-      `brightness=${formatNumber(brightness, 4)}:` +
-      `contrast=${formatNumber(contrast, 4)}:` +
-      `saturation=${formatNumber(saturation, 4)}:` +
-      `gamma=${formatNumber(gamma, 4)}` +
-      `${outputLabel};`,
-    amount,
-  };
+  if (effectClip.effect === "colorAdjust") {
+    const brightness =
+      typeof params.brightness === "number" ? params.brightness : 0;
+    const contrast =
+      typeof params.contrast === "number" ? params.contrast : 1;
+    const saturation =
+      typeof params.saturation === "number" ? params.saturation : 1;
+    const gamma = typeof params.gamma === "number" ? params.gamma : 1;
+
+    return {
+      filter:
+        `${inputLabel}eq=` +
+        `brightness=${formatNumber(brightness, 4)}:` +
+        `contrast=${formatNumber(contrast, 4)}:` +
+        `saturation=${formatNumber(saturation, 4)}:` +
+        `gamma=${formatNumber(gamma, 4)}` +
+        `${outputLabel};`,
+      amount,
+    };
+  }
+
+  if (effectClip.effect === "sepia") {
+    // Classic sepia tone via color channel mixer matrix
+    return {
+      filter:
+        `${inputLabel}colorchannelmixer=` +
+        `.393:.769:.189:0:` +
+        `.349:.686:.168:0:` +
+        `.272:.534:.131:0` +
+        `${outputLabel};`,
+      amount,
+    };
+  }
+
+  if (effectClip.effect === "blackAndWhite") {
+    const contrast =
+      typeof params.contrast === "number" ? params.contrast : 1;
+    let chain = `${inputLabel}hue=s=0`;
+    if (contrast !== 1) {
+      chain += `,eq=contrast=${formatNumber(contrast, 4)}`;
+    }
+    return {
+      filter: `${chain}${outputLabel};`,
+      amount,
+    };
+  }
+
+  if (effectClip.effect === "sharpen") {
+    // strength controls the unsharp amount (0-3, default 1.0), 5x5 luma matrix
+    const strength = clamp(
+      typeof params.strength === "number" ? params.strength : 1.0,
+      0,
+      3
+    );
+    return {
+      filter: `${inputLabel}unsharp=5:5:${formatNumber(strength, 4)}${outputLabel};`,
+      amount,
+    };
+  }
+
+  if (effectClip.effect === "chromaticAberration") {
+    // shift is horizontal pixel offset for red/blue channels (default 4, range 0-20)
+    const shift = clamp(
+      typeof params.shift === "number" ? params.shift : 4,
+      0,
+      20
+    );
+    const shiftInt = Math.round(shift);
+    return {
+      filter: `${inputLabel}rgbashift=rh=${shiftInt}:bh=${-shiftInt}${outputLabel};`,
+      amount,
+    };
+  }
+
+  if (effectClip.effect === "letterbox") {
+    // size is bar height as fraction of frame height (default 0.12, range 0-0.5)
+    const size = clamp(
+      typeof params.size === "number" ? params.size : 0.12,
+      0,
+      0.5
+    );
+    const color = typeof params.color === "string" ? params.color : "black";
+    const barExpr = `round(ih*${formatNumber(size, 4)})`;
+    return {
+      filter:
+        `${inputLabel}` +
+        `drawbox=y=0:w=iw:h='${barExpr}':color=${color}:t=fill,` +
+        `drawbox=y='ih-${barExpr}':w=iw:h='${barExpr}':color=${color}:t=fill` +
+        `${outputLabel};`,
+      amount,
+    };
+  }
+
+  // Unknown effect — guard against silent fallthrough
+  throw new Error(
+    `Unknown effect type '${effectClip.effect}' in buildProcessedEffectFilter`
+  );
 }
 
 function buildEffectFilters(effectClips, inputLabel) {

package/src/loaders.js

@@ -154,7 +154,7 @@ async function loadBackgroundAudio(project, clipObj) {
 function loadText(project, clipObj) {
   const clip = {
     ...clipObj,
-    fontFile: clipObj.fontFile || null,
+    fontFile: clipObj.fontFile || project.options.fontFile || null,
     fontFamily: clipObj.fontFamily || C.DEFAULT_FONT_FAMILY,
     fontSize: clipObj.fontSize || C.DEFAULT_FONT_SIZE,
     fontColor: clipObj.fontColor || C.DEFAULT_FONT_COLOR,
@@ -180,7 +180,6 @@ function loadEffect(project, clipObj) {
     ...clipObj,
     fadeIn: typeof clipObj.fadeIn === "number" ? clipObj.fadeIn : 0,
     fadeOut: typeof clipObj.fadeOut === "number" ? clipObj.fadeOut : 0,
-    easing: clipObj.easing || "linear",
     params: clipObj.params || {},
   };
   project.effectClips.push(clip);

package/src/schema/modules/effect.js

@@ -5,23 +5,38 @@ module.exports = {
     "Overlay adjustment clips that apply timed visual effects to the composed video (they do not create visual content by themselves).",
   schema: `{
   type: "effect";                           // Required: clip type identifier
-  effect: "vignette" | "filmGrain" | "gaussianBlur" | "colorAdjust"; // Required: effect kind
+  effect: "vignette" | "filmGrain" | "gaussianBlur" | "colorAdjust"
+        | "sepia" | "blackAndWhite" | "sharpen" | "chromaticAberration"
+        | "letterbox";                      // Required: effect kind
   position: number;                         // Required: start time on timeline (seconds)
   end?: number;                             // End time on timeline (seconds). Use end OR duration, not both.
   duration?: number;                        // Duration in seconds (alternative to end). end = position + duration.
   fadeIn?: number;                          // Optional: seconds to ramp in from 0 to full intensity
   fadeOut?: number;                         // Optional: seconds to ramp out from full intensity to 0
-  easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out"; // Optional envelope easing (default: "linear")
   params: EffectParams;                     // Required: effect-specific parameters
 }`,
   enums: {
-    EffectType: ["vignette", "filmGrain", "gaussianBlur", "colorAdjust"],
-    EffectEasing: ["linear", "ease-in", "ease-out", "ease-in-out"],
+    EffectType: [
+      "vignette",
+      "filmGrain",
+      "gaussianBlur",
+      "colorAdjust",
+      "sepia",
+      "blackAndWhite",
+      "sharpen",
+      "chromaticAberration",
+      "letterbox",
+    ],
     VignetteParams: `{ amount?: number; angle?: number; }`,
-    FilmGrainParams: `{ amount?: number; temporal?: boolean; }`,
+    FilmGrainParams: `{ amount?: number; strength?: number; temporal?: boolean; }`,
     GaussianBlurParams: `{ amount?: number; sigma?: number; }`,
     ColorAdjustParams:
       `{ amount?: number; brightness?: number; contrast?: number; saturation?: number; gamma?: number; }`,
+    SepiaParams: `{ amount?: number; }`,
+    BlackAndWhiteParams: `{ amount?: number; contrast?: number; }`,
+    SharpenParams: `{ amount?: number; strength?: number; }`,
+    ChromaticAberrationParams: `{ amount?: number; shift?: number; }`,
+    LetterboxParams: `{ amount?: number; size?: number; color?: string; }`,
   },
   examples: [
     {
@@ -36,7 +51,7 @@ module.exports = {
 }`,
     },
     {
-      label: "Film grain only during the middle section",
+      label: "Film grain with independent strength and blend",
       code: `{
   type: "effect",
   effect: "filmGrain",
@@ -44,8 +59,7 @@ module.exports = {
   end: 8,
   fadeIn: 0.4,
   fadeOut: 0.6,
-  easing: "ease-in-out",
-  params: { amount: 0.45, temporal: true }
+  params: { amount: 0.8, strength: 0.35, temporal: true }
 }`,
     },
     {
@@ -63,6 +77,38 @@ module.exports = {
     gamma: 1.04,
     brightness: -0.02
   }
+}`,
+    },
+    {
+      label: "Warm sepia tone",
+      code: `{
+  type: "effect",
+  effect: "sepia",
+  position: 0,
+  duration: 5,
+  fadeIn: 0.5,
+  params: { amount: 0.85 }
+}`,
+    },
+    {
+      label: "Black and white with contrast boost",
+      code: `{
+  type: "effect",
+  effect: "blackAndWhite",
+  position: 2,
+  end: 6,
+  params: { amount: 1, contrast: 1.3 }
+}`,
+    },
+    {
+      label: "Cinematic letterbox bars",
+      code: `{
+  type: "effect",
+  effect: "letterbox",
+  position: 0,
+  duration: 8,
+  fadeIn: 0.8,
+  params: { size: 0.12 }
 }`,
     },
   ],
@@ -71,7 +117,8 @@ module.exports = {
     "Effects do not satisfy visual timeline continuity checks and do not fill gaps.",
     "Use duration instead of end to specify length: end = position + duration. Cannot use both.",
     "position is required for effect clips (no auto-sequencing).",
-    "fadeIn/fadeOut are optional envelope controls that avoid abrupt on/off changes.",
+    "fadeIn/fadeOut are optional linear envelope controls that avoid abrupt on/off changes.",
     "params.amount is a normalized blend amount from 0 to 1 (default: 1).",
+    "filmGrain: use params.strength (0-1) for noise intensity, params.amount for blend alpha.",
   ],
 };

package/src/simpleffmpeg.js

@@ -56,6 +56,7 @@ class SIMPLEFFMPEG {
    * @param {number} options.fps - Frames per second (default: 30)
    * @param {string} options.preset - Platform preset ('tiktok', 'youtube', 'instagram-post', etc.)
    * @param {string} options.validationMode - Validation behavior: 'warn' or 'strict' (default: 'warn')
+   * @param {string} options.fontFile - Default font file path (.ttf, .otf) applied to all text clips unless overridden per-clip
    *
    * @example
    * const project = new SIMPLEFFMPEG({ preset: 'tiktok' });
@@ -87,6 +88,7 @@ class SIMPLEFFMPEG {
       height: options.height || presetConfig.height || C.DEFAULT_HEIGHT,
       validationMode: options.validationMode || C.DEFAULT_VALIDATION_MODE,
       preset: options.preset || null,
+      fontFile: options.fontFile || null,
     };
     this.videoOrAudioClips = [];
     this.textClips = [];

package/types/index.d.mts

@@ -246,8 +246,16 @@ declare namespace SIMPLEFFMPEG {
     transition?: { type: string; duration: number };
   }
 
-  type EffectName = "vignette" | "filmGrain" | "gaussianBlur" | "colorAdjust";
-  type EffectEasing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
+  type EffectName =
+    | "vignette"
+    | "filmGrain"
+    | "gaussianBlur"
+    | "colorAdjust"
+    | "sepia"
+    | "blackAndWhite"
+    | "sharpen"
+    | "chromaticAberration"
+    | "letterbox";
 
   interface EffectParamsBase {
     amount?: number;
@@ -258,6 +266,7 @@ declare namespace SIMPLEFFMPEG {
   }
 
   interface FilmGrainEffectParams extends EffectParamsBase {
+    strength?: number;
     temporal?: boolean;
   }
 
@@ -272,11 +281,35 @@ declare namespace SIMPLEFFMPEG {
     gamma?: number;
   }
 
+  interface SepiaEffectParams extends EffectParamsBase {}
+
+  interface BlackAndWhiteEffectParams extends EffectParamsBase {
+    contrast?: number;
+  }
+
+  interface SharpenEffectParams extends EffectParamsBase {
+    strength?: number;
+  }
+
+  interface ChromaticAberrationEffectParams extends EffectParamsBase {
+    shift?: number;
+  }
+
+  interface LetterboxEffectParams extends EffectParamsBase {
+    size?: number;
+    color?: string;
+  }
+
   type EffectParams =
     | VignetteEffectParams
     | FilmGrainEffectParams
     | GaussianBlurEffectParams
-    | ColorAdjustEffectParams;
+    | ColorAdjustEffectParams
+    | SepiaEffectParams
+    | BlackAndWhiteEffectParams
+    | SharpenEffectParams
+    | ChromaticAberrationEffectParams
+    | LetterboxEffectParams;
 
   /** Effect clip — timed overlay adjustment layer over composed video */
   interface EffectClip {
@@ -287,7 +320,6 @@ declare namespace SIMPLEFFMPEG {
     duration?: number;
     fadeIn?: number;
     fadeOut?: number;
-    easing?: EffectEasing;
     params: EffectParams;
   }
 
@@ -389,6 +421,8 @@ declare namespace SIMPLEFFMPEG {
     height?: number;
     /** Validation mode: 'warn' logs warnings, 'strict' throws on warnings (default: 'warn') */
     validationMode?: "warn" | "strict";
+    /** Default font file path (.ttf, .otf) applied to all text clips. Individual clips can override this with their own fontFile. */
+    fontFile?: string;
   }
 
   /** Log entry passed to onLog callback */

package/types/index.d.ts

@@ -246,8 +246,16 @@ declare namespace SIMPLEFFMPEG {
     transition?: { type: string; duration: number };
   }
 
-  type EffectName = "vignette" | "filmGrain" | "gaussianBlur" | "colorAdjust";
-  type EffectEasing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
+  type EffectName =
+    | "vignette"
+    | "filmGrain"
+    | "gaussianBlur"
+    | "colorAdjust"
+    | "sepia"
+    | "blackAndWhite"
+    | "sharpen"
+    | "chromaticAberration"
+    | "letterbox";
 
   interface EffectParamsBase {
     /** Base blend amount from 0 to 1 (default: 1) */
@@ -260,6 +268,8 @@ declare namespace SIMPLEFFMPEG {
   }
 
   interface FilmGrainEffectParams extends EffectParamsBase {
+    /** Noise intensity 0-1 (default: 0.35). Independent from blend amount. */
+    strength?: number;
     /** Temporal grain changes every frame (default: true) */
     temporal?: boolean;
   }
@@ -276,11 +286,40 @@ declare namespace SIMPLEFFMPEG {
     gamma?: number;
   }
 
+  interface SepiaEffectParams extends EffectParamsBase {}
+
+  interface BlackAndWhiteEffectParams extends EffectParamsBase {
+    /** Optional contrast boost (default: 1, range 0-3) */
+    contrast?: number;
+  }
+
+  interface SharpenEffectParams extends EffectParamsBase {
+    /** Unsharp amount (default: 1.0, range 0-3) */
+    strength?: number;
+  }
+
+  interface ChromaticAberrationEffectParams extends EffectParamsBase {
+    /** Horizontal pixel offset for R/B channels (default: 4, range 0-20) */
+    shift?: number;
+  }
+
+  interface LetterboxEffectParams extends EffectParamsBase {
+    /** Bar height as fraction of frame height (default: 0.12, range 0-0.5) */
+    size?: number;
+    /** Bar color (default: "black") */
+    color?: string;
+  }
+
   type EffectParams =
     | VignetteEffectParams
     | FilmGrainEffectParams
     | GaussianBlurEffectParams
-    | ColorAdjustEffectParams;
+    | ColorAdjustEffectParams
+    | SepiaEffectParams
+    | BlackAndWhiteEffectParams
+    | SharpenEffectParams
+    | ChromaticAberrationEffectParams
+    | LetterboxEffectParams;
 
   /** Effect clip — timed overlay adjustment layer over composed video */
   interface EffectClip {
@@ -296,8 +335,6 @@ declare namespace SIMPLEFFMPEG {
     fadeIn?: number;
     /** Ramp-out duration in seconds */
     fadeOut?: number;
-    /** Envelope easing for fade ramps */
-    easing?: EffectEasing;
     /** Effect-specific params */
     params: EffectParams;
   }
@@ -400,6 +437,8 @@ declare namespace SIMPLEFFMPEG {
     height?: number;
     /** Validation mode: 'warn' logs warnings, 'strict' throws on warnings (default: 'warn') */
     validationMode?: "warn" | "strict";
+    /** Default font file path (.ttf, .otf) applied to all text clips. Individual clips can override this with their own fontFile. */
+    fontFile?: string;
   }
 
   /** Log entry passed to onLog callback */