@effing/ffs 0.1.0

package/LICENSE

@@ -0,0 +1,11 @@
+O'Saasy License
+
+Copyright © 2026, Trackuity BV.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+2. No licensee or downstream recipient may use the Software (including any modified or derivative versions) to directly compete with the original Licensor by offering it to third parties as a hosted, managed, or Software-as-a-Service (SaaS) product or cloud service where the primary value of the service is the functionality of the Software itself.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,368 @@
+# @effing/ffs
+
+**FFmpeg-based video renderer for Effie compositions.**
+
+> Part of the [**Effing**](../../README.md) family — programmatic video creation with TypeScript.
+
+Takes an `EffieData` composition and renders it to an MP4 video using FFmpeg. Use as a library or run as a standalone HTTP server.
+
+## Installation
+
+```bash
+npm install @effing/ffs
+```
+
+FFmpeg is bundled via `ffmpeg-static` — no system installation required.
+
+## Quick Start
+
+### As a Library
+
+```typescript
+import { EffieRenderer } from "@effing/ffs";
+
+const renderer = new EffieRenderer(effieData);
+const videoStream = await renderer.render();
+
+// Pipe to file
+videoStream.pipe(fs.createWriteStream("output.mp4"));
+
+// Or pipe to HTTP response
+videoStream.pipe(res);
+
+// Clean up when done
+renderer.close();
+```
+
+### As an HTTP Server
+
+```bash
+# Run the server
+npx @effing/ffs
+
+# Or with custom port
+FFS_PORT=8080 npx @effing/ffs
+```
+
+Rendering is a two-step process with the HTTP server: first obtain a stream URL, then stream that URL to get the video.
+
+```bash
+# 1. Obtain a stream URL
+curl -X POST http://localhost:2000/render \
+  -H "Content-Type: application/json" \
+  -d @composition.json
+# Returns: { "id": "...", "url": "http://localhost:2000/render/123e4567-e89b-12d3-a456-426614174000" }
+
+# 2. Stream the URL to get the video
+curl http://localhost:2000/render/123e4567-e89b-12d3-a456-426614174000 -o output.mp4
+```
+
+#### Environment Variables
+
+| Variable                | Description                                   |
+| ----------------------- | --------------------------------------------- |
+| `FFS_PORT`              | Server port (default: 2000)                   |
+| `FFS_BASE_URL`          | Base URL for returned URLs                    |
+| `FFS_API_KEY`           | API key for authentication (optional)         |
+| `FFS_CACHE_BUCKET`      | S3 bucket for cache (enables S3 mode)         |
+| `FFS_CACHE_ENDPOINT`    | S3-compatible endpoint (for e.g. R2 or MinIO) |
+| `FFS_CACHE_REGION`      | AWS region (default: "auto")                  |
+| `FFS_CACHE_PREFIX`      | Key prefix for cached objects                 |
+| `FFS_CACHE_ACCESS_KEY`  | S3 access key ID                              |
+| `FFS_CACHE_SECRET_KEY`  | S3 secret access key                          |
+| `FFS_CACHE_LOCAL_DIR`   | Local cache directory (when not using S3)     |
+| `FFS_CACHE_TTL_MS`      | Cache TTL in milliseconds (default: 60 min)   |
+| `FFS_CACHE_CONCURRENCY` | Concurrent fetches during warmup (default: 4) |
+
+When `FFS_CACHE_BUCKET` is not set, FFS uses the local filesystem for caching (default: system temp directory). Local cache files are automatically cleaned up after the TTL expires.
+
+For S3 storage, the TTL is set as the `Expires` header on objects. Note that this is metadata only. To enable automatic deletion, configure [S3 lifecycle rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) on your bucket to delete expired objects.
+
+## Concepts
+
+### EffieRenderer
+
+The main class that orchestrates video rendering:
+
+1. **Builds FFmpeg command** — Constructs complex filter graphs for overlays, transitions, effects
+2. **Fetches sources** — Downloads images, animations, and audio from URLs
+3. **Processes layers** — Applies motion, effects, and timing to each layer
+4. **Outputs video** — Streams H.264/AAC MP4 to stdout or file
+
+## API Overview
+
+### EffieRenderer
+
+```typescript
+class EffieRenderer {
+  constructor(effieData: EffieData<EffieSources>);
+
+  // Render composition
+  render(scaleFactor?: number): Promise<Readable>;
+
+  // Clean up FFmpeg process
+  close(): void;
+}
+```
+
+### FFmpegCommand & FFmpegRunner
+
+Lower-level classes for building and executing FFmpeg commands:
+
+```typescript
+import { FFmpegCommand, FFmpegRunner } from "@effing/ffs";
+
+const cmd = new FFmpegCommand(globalArgs, inputs, filterComplex, outputArgs);
+const runner = new FFmpegRunner(cmd);
+const output = await runner.run(fetchSource, transformImage);
+```
+
+### Processing Functions
+
+```typescript
+import { processMotion, processEffects, processTransition } from "@effing/ffs";
+
+// Convert motion config to FFmpeg overlay expression
+const overlayExpr = processMotion(delay, motionConfig);
+
+// Build effect filter chain
+const filters = processEffects(effects, fps, width, height);
+
+// Get FFmpeg transition name
+const xfadeName = processTransition(transition);
+```
+
+## Server Endpoints
+
+When running as an HTTP server, FFS provides endpoints for rendering, cache warmup, and cache purging.
+
+### `POST /render`
+
+Creates a render job and returns a stream URL to execute it. Supports two request formats:
+
+**Raw EffieData**: Body is raw EffieData, options in query params.
+
+| Query Param | Effect                    |
+| ----------- | ------------------------- |
+| `scale`     | Scale factor (default: 1) |
+
+**Wrapped format**: Body contains `effie` plus options.
+
+```typescript
+type RenderOptions = {
+  effie: EffieData | string; // EffieData object or URL to fetch from
+  scale?: number; // Scale factor (default: 1)
+  upload?: {
+    videoUrl: string; // Pre-signed URL to upload rendered video
+    coverUrl?: string; // Pre-signed URL to upload cover image
+  };
+};
+```
+
+| Option         | Effect                                         |
+| -------------- | ---------------------------------------------- |
+| `effie` as URL | Fetches EffieData from the URL before storing  |
+| `upload`       | GET will upload and stream SSE progress events |
+
+**Response:**
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "url": "http://localhost:2000/render/550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+### `GET /render/:id`
+
+Executes the render job. Behavior depends on whether `upload` was specified:
+
+**Without upload** — Streams the MP4 video directly:
+
+```bash
+curl http://localhost:2000/render/550e8400-... -o output.mp4
+```
+
+**With upload** — Streams progress via Server-Sent Events (SSE) while uploading:
+
+| Event       | Data                                                       |
+| ----------- | ---------------------------------------------------------- |
+| `started`   | `{ "status": "rendering" }`                                |
+| `keepalive` | `{ "status": "rendering" }` or `{ "status": "uploading" }` |
+| `complete`  | `{ "status": "uploaded", "timings": {...} }`               |
+| `error`     | `{ "message": "..." }`                                     |
+
+**Example:**
+
+```typescript
+// Create render job
+const { url } = await fetch("/render", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ effie: effieData, scale: 0.5 }),
+}).then((r) => r.json());
+
+// Stream video directly
+const videoResponse = await fetch(url);
+const videoBlob = await videoResponse.blob();
+```
+
+### `POST /warmup`
+
+Creates a warmup job for pre-fetching and caching the sources from an Effie composition. Use this to avoid render timeouts when sources (especially annies) take a long time to generate.
+
+**Request:** Same format as `/render` (raw or wrapped EffieData with `effie` field).
+
+**Response:**
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "url": "http://localhost:2000/warmup/550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+### `GET /warmup/:id`
+
+Runs the cache warmup job and streams the progress via Server-Sent Events (SSE). Connect with `EventSource` for real-time updates.
+
+**Events:**
+
+| Event         | Data                                                                                         |
+| ------------- | -------------------------------------------------------------------------------------------- |
+| `start`       | `{ "total": 5 }`                                                                             |
+| `progress`    | `{ "url": "...", "status": "hit"\|"cached"\|"error", "cached": 2, "failed": 0, "total": 5 }` |
+| `downloading` | `{ "url": "...", "status": "downloading", "bytesReceived": 1048576 }`                        |
+| `keepalive`   | `{ "cached": 2, "failed": 0, "total": 5 }`                                                   |
+| `summary`     | `{ "cached": 5, "failed": 0, "total": 5 }`                                                   |
+| `complete`    | `{ "status": "ready" }`                                                                      |
+
+**Example:**
+
+```typescript
+// Create warmup job
+const { url } = await fetch("/warmup", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ effie: effieData }),
+}).then((r) => r.json());
+
+// Stream progress (url is a full URL)
+const events = new EventSource(url);
+events.addEventListener("complete", () => {
+  events.close();
+  // Now safe to call /render
+});
+```
+
+### `POST /purge`
+
+Purges cached sources for a given Effie composition.
+
+**Request:** Same format as `/render` (raw or wrapped EffieData with `effie` field).
+
+**Response:**
+
+```json
+{ "purged": 3, "total": 5 }
+```
+
+## Examples
+
+### Scale Factor for Previews
+
+Render at reduced resolution for faster previews:
+
+```typescript
+const renderer = new EffieRenderer(video);
+
+// Render at 50% resolution
+const previewStream = await renderer.render(0.5);
+```
+
+### Distributed Rendering
+
+For videos with many segments, you can render in parallel using the partitioning helpers from `@effing/effie`:
+
+```typescript
+import { EffieRenderer } from "@effing/ffs";
+import { effieDataForSegment, effieDataForJoin } from "@effing/effie";
+
+const effieData = /* ... */;
+
+// 1. Render each segment (can be parallelized across workers/servers)
+const segmentUrls = await Promise.all(
+  effieData.segments.map(async (_, i) => {
+    const segEffie = effieDataForSegment(effieData, i);
+    const renderer = new EffieRenderer(segEffie);
+    const stream = await renderer.render();
+    // Upload to storage and get URL
+    const url = await uploadToStorage(stream, `segment_${i}.mp4`);
+    renderer.close();
+    return url;
+  })
+);
+
+// 2. Join segments with transitions and global audio
+const joinEffie = effieDataForJoin(effieData, segmentUrls);
+const joinRenderer = new EffieRenderer(joinEffie);
+const finalStream = await joinRenderer.render();
+```
+
+### Server API Examples
+
+**Create render job and stream video:**
+
+```typescript
+// Create render job
+const { url } = await fetch("http://localhost:2000/render", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ effie: effieData, scale: 0.5 }),
+}).then((r) => r.json());
+
+// Stream the video
+const video = await fetch(url).then((r) => r.blob());
+```
+
+**Fetch from URL and render:**
+
+```typescript
+const { url } = await fetch("http://localhost:2000/render", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    effie: "https://example.com/composition.json",
+    scale: 0.5,
+  }),
+}).then((r) => r.json());
+```
+
+**Render and upload to S3 (SSE progress):**
+
+```typescript
+const { url } = await fetch("http://localhost:2000/render", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    effie: effieData,
+    upload: {
+      videoUrl: "https://s3.../presigned-video-url",
+      coverUrl: "https://s3.../presigned-cover-url",
+    },
+  }),
+}).then((r) => r.json());
+
+// Connect to SSE for progress
+const events = new EventSource(url);
+events.addEventListener("complete", (e) => {
+  const { timings } = JSON.parse(e.data);
+  console.log("Uploaded!", timings);
+  events.close();
+});
+```
+
+## Related Packages
+
+- [`@effing/effie`](../effie) — Define video compositions
+- [`@effing/annie`](../annie) — Generate animations for layers

package/dist/cache-BUVFfGZF.d.ts

@@ -0,0 +1,25 @@
+import { Readable } from 'stream';
+
+/**
+ * Cache storage interface
+ */
+interface CacheStorage {
+    /** Store a stream with the given key */
+    put(key: string, stream: Readable): Promise<void>;
+    /** Get a stream for the given key, or null if not found */
+    getStream(key: string): Promise<Readable | null>;
+    /** Check if a key exists */
+    exists(key: string): Promise<boolean>;
+    /** Check if multiple keys exist (batch operation) */
+    existsMany(keys: string[]): Promise<Map<string, boolean>>;
+    /** Delete a key */
+    delete(key: string): Promise<void>;
+    /** Store JSON data */
+    putJson(key: string, data: object): Promise<void>;
+    /** Get JSON data, or null if not found */
+    getJson<T>(key: string): Promise<T | null>;
+    /** Close and cleanup resources */
+    close(): void;
+}
+
+export type { CacheStorage as C };