Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

deploy media lambda as a managed zip service

kashorin95dd2fb59852
diff --git a/package.json b/package.json
index ac356656..064a4fc1 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,8 @@
"smoke:kie": "node --import tsx packages/provider-kie/test/live-smoke.ts",
"narratage": "node --import tsx packages/video-cli/src/cli.ts",
"svml": "node --import tsx packages/video-cli/src/cli.ts",
- "build:media-lambda": "pnpm --filter @narratage/media-lambda build"
+ "build:media-lambda": "pnpm --filter @narratage/media-lambda build",
+ "build:media-lambda-layer": "pnpm --filter @narratage/media-lambda build:layer"
},
"engines": {
"node": ">=22"
diff --git a/packages/media-execution/src/execute.ts b/packages/media-execution/src/execute.ts
index 5eb64e2f..d6e1d1b8 100644
--- a/packages/media-execution/src/execute.ts
+++ b/packages/media-execution/src/execute.ts
@@ -32,7 +32,7 @@ import { parseMediaInspection } from "./probe.js";
* These five operations are the whole of Narratage's media execution, and they
* are written once. A local Provider supplies the Build's own ArtifactStore and
* the ffmpeg on its PATH; a Lambda Provider supplies an S3-backed gateway and
- * the ffmpeg baked into its image. Nothing below knows which it is, so the two
+ * the ffmpeg carried by its deployment. Nothing below knows which it is, so the two
* deployments cannot drift into computing different media from one Need.
*/
export type MediaArtifactGateway = {
@@ -44,6 +44,8 @@ export type MediaExecutionEnvironment = {
readonly artifacts: MediaArtifactGateway;
readonly ffmpegPath: string;
readonly ffprobePath: string;
+ /** Deployment fact for dynamically linked tool bundles; absent for ordinary local binaries. */
+ readonly sharedLibraryPath?: string;
readonly processTimeoutMs: number;
readonly maxProbeOutputBytes: number;
/** Recorded in each result's metadata, so an Operation says which Provider ran it. */
@@ -92,12 +94,16 @@ async function runProcess(args: {
readonly argv: readonly string[];
readonly timeoutMs: number;
readonly maxStdoutBytes: number;
+ readonly sharedLibraryPath?: string;
}): Promise<Uint8Array> {
return await new Promise((resolve, reject) => {
const child = spawn(args.executable, [...args.argv], {
shell: false,
stdio: ["ignore", "pipe", "pipe"],
- env: { PATH: process.env.PATH ?? "" },
+ env: {
+ PATH: process.env.PATH ?? "",
+ ...(args.sharedLibraryPath === undefined ? {} : { LD_LIBRARY_PATH: args.sharedLibraryPath }),
+ },
});
const stdout: Buffer[] = [];
let stdoutBytes = 0;
@@ -134,8 +140,9 @@ async function runProcess(args: {
});
}
-async function version(executable: string, timeoutMs: number): Promise<string> {
- const bytes = await runProcess({ executable, argv: ["-version"], timeoutMs, maxStdoutBytes: 64 * 1024 });
+async function version(executable: string, timeoutMs: number, sharedLibraryPath?: string): Promise<string> {
+ const bytes = await runProcess({ executable, argv: ["-version"], timeoutMs, maxStdoutBytes: 64 * 1024,
+ ...(sharedLibraryPath === undefined ? {} : { sharedLibraryPath }) });
const line = Buffer.from(bytes).toString("utf8").split(/\r?\n/u, 1)[0]?.trim();
assert(line !== undefined && line.length > 0, `${executable} returned no version`);
return line;
@@ -297,6 +304,7 @@ async function inspectFile(args: {
readonly ffprobePath: string;
readonly timeoutMs: number;
readonly maxProbeOutputBytes: number;
+ readonly sharedLibraryPath?: string;
}): Promise<MediaInspection> {
const [raw, ffprobeVersion] = await Promise.all([
runProcess({
@@ -304,8 +312,9 @@ async function inspectFile(args: {
argv: ["-v", "error", "-print_format", "json", "-show_format", "-show_streams", "-show_frames", args.input],
timeoutMs: args.timeoutMs,
maxStdoutBytes: args.maxProbeOutputBytes,
+ ...(args.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: args.sharedLibraryPath }),
}),
- version(args.ffprobePath, args.timeoutMs),
+ version(args.ffprobePath, args.timeoutMs, args.sharedLibraryPath),
]);
let value: unknown;
try {
@@ -322,6 +331,7 @@ async function outputInspection(args: {
readonly ffprobePath: string;
readonly timeoutMs: number;
readonly maxProbeOutputBytes: number;
+ readonly sharedLibraryPath?: string;
}): Promise<MediaInspection> {
const bytes = await readFile(args.path);
const source: BlobRef = {
@@ -331,7 +341,8 @@ async function outputInspection(args: {
mediaType: args.mediaType,
};
return await inspectFile({ source, input: args.path, ffprobePath: args.ffprobePath,
- timeoutMs: args.timeoutMs, maxProbeOutputBytes: args.maxProbeOutputBytes });
+ timeoutMs: args.timeoutMs, maxProbeOutputBytes: args.maxProbeOutputBytes,
+ ...(args.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: args.sharedLibraryPath }) });
}
function result(value: CanonicalValue, metadata: CanonicalValue): MediaOperationResult {
@@ -432,6 +443,7 @@ async function assertCanonicalWav(args: {
readonly ffprobePath: string;
readonly timeoutMs: number;
readonly maxProbeOutputBytes: number;
+ readonly sharedLibraryPath?: string;
}): Promise<MediaAudioStream> {
const inspection = await inspectFile({
source: args.source,
@@ -439,6 +451,7 @@ async function assertCanonicalWav(args: {
ffprobePath: args.ffprobePath,
timeoutMs: args.timeoutMs,
maxProbeOutputBytes: args.maxProbeOutputBytes,
+ ...(args.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: args.sharedLibraryPath }),
});
const audio = inspection.streams.filter((item): item is MediaAudioStream => item.kind === "audio");
assert(audio.length === 1 && inspection.streams.length === 1, "Canonical audio must contain exactly one stream");
@@ -463,6 +476,7 @@ export async function executeInspectMedia(
ffprobePath: env.ffprobePath,
timeoutMs: env.processTimeoutMs,
maxProbeOutputBytes: env.maxProbeOutputBytes,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
return result(canonicalize(inspection), canonicalize({ provider: env.label, operation: "inspect" }));
} finally {
@@ -500,6 +514,7 @@ export async function executeNormalizeMedia(
"-preset", "veryfast", "-pix_fmt", "yuv420p", "-movflags", "+faststart", output],
timeoutMs: env.processTimeoutMs,
maxStdoutBytes: 64 * 1024,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
const inspected = await outputInspection({
path: output,
@@ -507,6 +522,7 @@ export async function executeNormalizeMedia(
ffprobePath: env.ffprobePath,
timeoutMs: env.processTimeoutMs,
maxProbeOutputBytes: env.maxProbeOutputBytes,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
const visual = inspected.streams.find((item): item is MediaVideoStream => item.kind === "video");
assert(visual?.decodedUnitCount === plan.frameCount && visual.role === "moving",
@@ -536,6 +552,7 @@ export async function executeNormalizeMedia(
"-c:a", "pcm_s16le", "-ar", "48000", "-ac", "2", output],
timeoutMs: env.processTimeoutMs,
maxStdoutBytes: 64 * 1024,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
const inspected = await outputInspection({
path: output,
@@ -543,6 +560,7 @@ export async function executeNormalizeMedia(
ffprobePath: env.ffprobePath,
timeoutMs: env.processTimeoutMs,
maxProbeOutputBytes: env.maxProbeOutputBytes,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
const audio = inspected.streams.find((item): item is MediaAudioStream => item.kind === "audio");
assert(audio?.decodedSampleFrames === plan.sampleFrames && audio.sampleRate === 48_000 && audio.channels === 2,
@@ -613,6 +631,7 @@ export async function executeProjectSpeechEvidenceAudio(
ffprobePath: env.ffprobePath,
timeoutMs: env.processTimeoutMs,
maxProbeOutputBytes: env.maxProbeOutputBytes,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
assert(source.decodedSampleFrames === need.sourceSampleFrames,
"Speech master sample count differs from its ProgramSpace");
@@ -630,6 +649,7 @@ export async function executeProjectSpeechEvidenceAudio(
"-c:a", "pcm_s16le", "-ar", "16000", "-ac", "1", output],
timeoutMs: env.processTimeoutMs,
maxStdoutBytes: 64 * 1024,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
const inspected = await outputInspection({
path: output,
@@ -637,6 +657,7 @@ export async function executeProjectSpeechEvidenceAudio(
ffprobePath: env.ffprobePath,
timeoutMs: env.processTimeoutMs,
maxProbeOutputBytes: env.maxProbeOutputBytes,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
const streams = inspected.streams.filter((item): item is MediaAudioStream => item.kind === "audio");
assert(streams.length === 1 && inspected.streams.length === 1
@@ -697,6 +718,7 @@ export async function executeRenderTimelineAudio(
ffprobePath: env.ffprobePath,
timeoutMs: env.processTimeoutMs,
maxProbeOutputBytes: env.maxProbeOutputBytes,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
assert(audio.decodedSampleFrames > 0, `Audio input ${clip.artifact.digest} is empty`);
artifacts.set(clip.artifact.digest, { source: clip.artifact, path, inputIndex });
@@ -729,6 +751,7 @@ export async function executeRenderTimelineAudio(
argv,
timeoutMs: env.processTimeoutMs,
maxStdoutBytes: 64 * 1024,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
const bytes = await readFile(output);
const artifact = await env.artifacts.put(bytes, "audio/wav");
@@ -738,6 +761,7 @@ export async function executeRenderTimelineAudio(
ffprobePath: env.ffprobePath,
timeoutMs: env.processTimeoutMs,
maxProbeOutputBytes: env.maxProbeOutputBytes,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
assert(audio.decodedSampleFrames === plan.sampleFrames,
"Rendered TimelineAudio sample count differs from its plan");
@@ -781,6 +805,7 @@ export async function executeMuxProgramMedia(
ffprobePath: env.ffprobePath,
timeoutMs: env.processTimeoutMs,
maxProbeOutputBytes: env.maxProbeOutputBytes,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
}),
assertCanonicalWav({
path: audioPath,
@@ -788,6 +813,7 @@ export async function executeMuxProgramMedia(
ffprobePath: env.ffprobePath,
timeoutMs: env.processTimeoutMs,
maxProbeOutputBytes: env.maxProbeOutputBytes,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
}),
]);
const visualStreams = visualInspection.streams.filter((item): item is MediaVideoStream => item.kind === "video");
@@ -811,6 +837,7 @@ export async function executeMuxProgramMedia(
],
timeoutMs: env.processTimeoutMs,
maxStdoutBytes: 64 * 1024,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
const finalInspection = await outputInspection({
path: output,
@@ -818,6 +845,7 @@ export async function executeMuxProgramMedia(
ffprobePath: env.ffprobePath,
timeoutMs: env.processTimeoutMs,
maxProbeOutputBytes: env.maxProbeOutputBytes,
+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
const finalVideo = finalInspection.streams.filter((item): item is MediaVideoStream => item.kind === "video");
const finalAudio = finalInspection.streams.filter((item): item is MediaAudioStream => item.kind === "audio");
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 07d3e783..5ef11de1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1774,15 +1774,27 @@ importers:
'@narratage/artifact-store-s3':
specifier: workspace:*
version: link:../../packages/artifact-store-s3
+ '@narratage/media':
+ specifier: workspace:*
+ version: link:../../packages/media
'@narratage/media-execution':
specifier: workspace:*
version: link:../../packages/media-execution
+ '@narratage/media-pipeline':
+ specifier: workspace:*
+ version: link:../../packages/media-pipeline
'@narratage/protocol':
specifier: workspace:*
version: link:../../packages/protocol
'@narratage/provider-media-aws-lambda':
specifier: workspace:*
version: link:../../packages/provider-media-aws-lambda
+ '@narratage/speech':
+ specifier: workspace:*
+ version: link:../../packages/speech
+ '@narratage/transport-aws-lambda':
+ specifier: workspace:*
+ version: link:../../packages/transport-aws-lambda
devDependencies:
esbuild:
specifier: ^0.25.0
diff --git a/services/media-lambda/README.md b/services/media-lambda/README.md
index 58519078..9d1a5850 100644
--- a/services/media-lambda/README.md
+++ b/services/media-lambda/README.md
@@ -1,89 +1,113 @@
-# Narratage media function
+# Narratage media execution service
-The five media Needs — inspect, normalize, speech-evidence projection, timeline audio and mux —
-executed in AWS Lambda instead of on the machine running the Build. This is deployment state, not
-an author-importable SVML package.
+This service answers the five media Needs — inspect, normalize, speech-evidence projection,
+timeline audio and mux — in AWS Lambda. It is deployment state, not an author-importable SVML
+package.
-It owns no media logic. `@narratage/media-execution` holds the FFmpeg arguments and frame/sample
-arithmetic, and the same code answers a local Build through `@narratage/provider-media-local`.
-This service contributes only an S3 byte gateway and one managed-runtime Lambda entry point.
+It owns no media semantics. `@narratage/media-execution` contains the FFmpeg commands and
+frame/sample arithmetic shared with `@narratage/provider-media-local`. This directory contributes
+an S3 byte gateway, a managed-runtime handler and one declarative AWS deployment.
-## Two immutable deployment objects
+## One stack, two immutable code objects
-The deployment is intentionally split:
+`template.yaml` makes one CloudFormation stack own:
-1. `build.mjs` produces a small Node.js 22 function ZIP containing the handler and all JavaScript
- dependencies;
-2. an independently published Lambda Layer supplies `/opt/bin/ffmpeg` and `/opt/bin/ffprobe`.
+- the narrowly scoped Lambda execution role;
+- its retained CloudWatch log group;
+- an immutable FFmpeg 8.0.1 Layer version;
+- the Node.js 22 media function;
+- a retained, immutable function version;
+- an explicit reserved-concurrency ceiling.
-`publish.sh` requires an exact Layer **version** ARN. It never selects a public Layer, never creates
-an ECR repository and never invokes Docker. On the first invocation in each warm environment the
-handler runs both binaries with `-version` and refuses the fulfillment unless both report FFmpeg
-8.0.1.
+The ArtifactStore bucket and deployment-artifact bucket remain external resources. The same
+ArtifactStore can serve local and Lambda Endpoints; the deployment bucket contains code, not Build
+Artifacts.
-The repository does not yet publish a redistributable FFmpeg Layer. That is deliberate: an exact
-binary build, its complete license surface, upstream archive digest and regional Layer versions are
-one supply-chain artifact of their own. Until that artifact is reviewed, the function packager is
-complete but a fresh account must provide its own compatible Layer.
+`build.mjs` produces the small function ZIP. `build-layer.mjs` downloads one exact BtbN archive,
+checks its SHA-256, retains only `ffmpeg`, `ffprobe`, their shared libraries and the upstream
+license, and creates a deterministic Layer ZIP. The Layer provenance is embedded as
+`/opt/narratage-layer.json`. Set `NARRATAGE_FFMPEG_SOURCE` to an already downloaded archive for an
+offline build; it is accepted only when its digest matches the pin.
-AWS mounts Layer `bin/` at `/opt/bin`. The reviewed Layer must therefore be:
+Shared-library links are copied verbatim from the upstream archive. The builder rejects absolute,
+escaping or dangling links before producing the ZIP, so a build-machine path cannot become a
+silent `/opt/lib` runtime failure.
-- Linux x86-64 and compatible with Amazon Linux 2023;
-- FFmpeg and FFprobe 8.0.1;
-- packaged with executable paths `bin/ffmpeg` and `bin/ffprobe`;
-- small enough that the uncompressed function plus all Layers remain within Lambda's quota;
-- published in the same region as the function, with an immutable version ARN; it may be a
- separately permitted cross-account Layer.
+The selected build is:
-## Data and authority
-
-The function and the Build share one S3 ArtifactStore. Media bytes never travel in the synchronous
-Lambda payload: requests name content-addressed objects, and results are written back under the same
-key rule as `@narratage/artifact-store-s3`.
-
-The execution role needs only read/write access to that Artifact prefix and CloudWatch Logs. The
-publisher needs permission to update the named ZIP function, pass that role and read the selected
-Layer version. Templates under `iam/` use `ACCOUNT_ID`, `REGION` and `BUCKET` placeholders.
+```text
+FFmpeg n8.0.1-66-g27b8d1a017
+linux64 GPL shared, x86-64
+source sha256 38f5363bef58d74547e5055846d76d8b20bb2872a87b0aab71611b010b437a6f
+```
-Credentials always reach AWS clients through the SDK default credential chain. Keys do not enter
-source, Runtime Profiles, BuildState or hand-assembled credential objects.
+AWS mounts Layer `bin/` and `lib/` as `/opt/bin` and `/opt/lib`. The handler additionally executes
+both binaries with `-version` once per warm environment and refuses work unless both report 8.0.1.
-## First-time AWS setup
+## Authority and bytes
-Create the shared Artifact bucket with public access blocked. Apply the substituted
-`iam/execution.json` to the `NarratageMediaExecution` role, using `iam/execution-trust.json` as its
-trust policy, and apply the substituted `iam/publisher.json` to the identity that publishes this
-function. The same bucket can be the S3 ArtifactStore used by the Runtime.
+The function role can only read and write objects in the selected ArtifactStore bucket and append
+to its own log group. It cannot deploy code, publish Layers, inspect IAM or access the deployment
+bucket.
-The default function name is `narratage-media-zip`. AWS cannot convert an existing image-packaged
-function to ZIP, so an old `narratage-media` image function can remain until its versioned ARN is no
-longer referenced.
+The deployer needs the reviewed actions in `iam/publisher.json`. CloudFormation uses the deployer's
+AWS credential chain; access keys never enter source, a Runtime Profile or BuildState.
-## Build and publish
+Media bytes never enter the synchronous Lambda request. Requests identify content-addressed S3
+objects and results are written back through the same `@narratage/artifact-store-s3` key rule.
-Building is local, network-free and creates no cloud resource:
+## Build without AWS
```bash
pnpm build:media-lambda
+pnpm build:media-lambda-layer
```
-It writes ignored files under `services/media-lambda/build/`: `index.mjs`, `function.zip`, the
-reviewed deployment description and its bundle hash.
+Ignored output is written under `services/media-lambda/build/`. The two artifact manifests record
+the function bundle hash, ZIP hashes, exact upstream source and package sizes.
-Publishing mutates AWS and therefore requires an already reviewed Layer version:
+## Plan, inspect, apply
+
+Deployment deliberately has two commands. `plan` may build and upload content-addressed packages,
+but it only creates a CloudFormation Change Set. `apply` accepts that exact Change Set ARN; it does
+not rebuild or silently reinterpret the plan.
```bash
+export AWS_PROFILE=narratage
export AWS_REGION=us-east-1
export AWS_ACCOUNT_ID=123456789012
-export NARRATAGE_MEDIA_BUCKET=your-artifact-bucket
-export NARRATAGE_FFMPEG_LAYER_ARN=arn:aws:lambda:us-east-1:123456789012:layer:narratage-ffmpeg-8-0-1:1
-./publish.sh
+export NARRATAGE_MEDIA_ENVIRONMENT=dev
+export NARRATAGE_MEDIA_STACK=narratage-media-dev
+export NARRATAGE_MEDIA_FUNCTION=narratage-media-dev
+export NARRATAGE_MEDIA_ROLE=NarratageMediaExecution-dev
+export NARRATAGE_MEDIA_LAYER=narratage-ffmpeg-8-0-1
+export NARRATAGE_MEDIA_ARTIFACT_BUCKET=narratage-artifacts-123456789012
+export NARRATAGE_MEDIA_DEPLOYMENT_BUCKET=your-regional-deployment-bucket
+
+services/media-lambda/deploy.sh plan
+services/media-lambda/deploy.sh apply <exact-change-set-arn>
```
-The script verifies region affinity, resolves the Layer before mutation, creates or updates
-the ZIP function, verifies the complete effective configuration, publishes an immutable function
-version and prints the Runtime Profile Endpoint entry. The Provider refuses an unqualified
-function ARN.
+Optional infrastructure parameters are `NARRATAGE_MEDIA_MEMORY` (3008),
+`NARRATAGE_MEDIA_EPHEMERAL` (8192), `NARRATAGE_MEDIA_CONCURRENCY` (8) and
+`NARRATAGE_MEDIA_LOG_RETENTION_DAYS` (14). They are CloudFormation parameters and therefore visible
+in the Change Set.
+
+The stack outputs an immutable function-version ARN and a complete JSON Endpoint entry for
+`@narratage/provider-media-aws-lambda`. The Provider rejects an unqualified function name. Old
+function and Layer versions are retained across updates so a recorded Runtime Profile never changes
+meaning because a newer deployment happened.
+
+## Live canary
+
+The canary generates a one-second local fixture and runs all five remote media operations. Its S3
+prefix is isolated and removed after success or failure unless `NARRATAGE_MEDIA_CANARY_KEEP=1`.
+
+```bash
+export NARRATAGE_MEDIA_FUNCTION_ARN=arn:aws:lambda:us-east-1:123456789012:function:narratage-media-dev:1
+export NARRATAGE_MEDIA_ARTIFACT_BUCKET=narratage-artifacts-123456789012
+pnpm --filter @narratage/media-lambda canary
+```
-No real AWS deployment is part of the normal test suite. The handler itself is exercised with real
-local FFmpeg over an in-memory bucket, including rejection of a Layer version mismatch.
+No paid AWS deployment runs in the normal test suite. The handler tests execute the real shared
+media implementation with local FFmpeg and an in-memory object store.
diff --git a/services/media-lambda/build-layer.mjs b/services/media-lambda/build-layer.mjs
new file mode 100755
index 00000000..3d3a7996
--- /dev/null
+++ b/services/media-lambda/build-layer.mjs
@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import {
+ chmod,
+ cp,
+ lstat,
+ lutimes,
+ mkdir,
+ readlink,
+ readFile,
+ readdir,
+ rename,
+ rm,
+ stat,
+ utimes,
+ writeFile,
+} from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const SOURCE_NAME = "ffmpeg-n8.0.1-66-g27b8d1a017-linux64-gpl-shared-8.0.tar.xz";
+const SOURCE_URL =
+ `https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-02-28-12-59/${SOURCE_NAME}`;
+const SOURCE_SHA256 = "38f5363bef58d74547e5055846d76d8b20bb2872a87b0aab71611b010b437a6f";
+const FFmpeg_VERSION = "8.0.1";
+const EPOCH = new Date("1980-01-01T00:00:00.000Z");
+
+const root = dirname(fileURLToPath(import.meta.url));
+const out = join(root, "build");
+const source = process.env.NARRATAGE_FFMPEG_SOURCE ?? join(out, SOURCE_NAME);
+const work = join(out, "ffmpeg-layer-work");
+const extracted = join(work, "source");
+const layer = join(work, "layer");
+const archive = join(out, "ffmpeg-layer.zip");
+const manifestPath = join(out, "ffmpeg-layer-artifact.json");
+
+async function sha256(path) {
+ const hash = createHash("sha256");
+ for await (const chunk of createReadStream(path)) hash.update(chunk);
+ return hash.digest("hex");
+}
+
+async function ensureSource() {
+ await mkdir(out, { recursive: true });
+ try {
+ if (await sha256(source) === SOURCE_SHA256) return;
+ } catch (error) {
+ if (error?.code !== "ENOENT") throw error;
+ }
+ if (process.env.NARRATAGE_FFMPEG_SOURCE !== undefined) {
+ throw new Error(`NARRATAGE_FFMPEG_SOURCE does not match pinned sha256 ${SOURCE_SHA256}`);
+ }
+
+ const temporary = `${source}.partial`;
+ await rm(temporary, { force: true });
+ const response = await fetch(SOURCE_URL, { redirect: "follow" });
+ if (!response.ok || response.body === null) {
+ throw new Error(`failed to download pinned FFmpeg archive: HTTP ${response.status}`);
+ }
+ await pipeline(Readable.fromWeb(response.body), createWriteStream(temporary, { mode: 0o644 }));
+ const actual = await sha256(temporary);
+ if (actual !== SOURCE_SHA256) {
+ await rm(temporary, { force: true });
+ throw new Error(`FFmpeg source digest mismatch: expected ${SOURCE_SHA256}, got ${actual}`);
+ }
+ await rename(temporary, source);
+}
+
+async function entriesUnder(path, found = []) {
+ const children = (await readdir(path)).sort();
+ for (const name of children) {
+ const child = join(path, name);
+ const info = await lstat(child);
+ if (info.isDirectory()) await entriesUnder(child, found);
+ else found.push(child);
+ }
+ return found;
+}
+
+async function normalize(path) {
+ const children = (await readdir(path)).sort();
+ for (const name of children) {
+ const child = join(path, name);
+ const info = await lstat(child);
+ if (info.isDirectory()) {
+ await normalize(child);
+ await chmod(child, 0o755);
+ await utimes(child, EPOCH, EPOCH);
+ } else if (info.isSymbolicLink()) {
+ await lutimes(child, EPOCH, EPOCH);
+ } else {
+ await chmod(child, relative(layer, child).startsWith("bin/") ? 0o755 : 0o644);
+ await utimes(child, EPOCH, EPOCH);
+ }
+ }
+ await chmod(path, 0o755);
+ await utimes(path, EPOCH, EPOCH);
+}
+
+await ensureSource();
+if (await sha256(source) !== SOURCE_SHA256) throw new Error("pinned FFmpeg source changed during build");
+await rm(work, { recursive: true, force: true });
+await rm(archive, { force: true });
+await mkdir(extracted, { recursive: true });
+await mkdir(layer, { recursive: true });
+await promisify(execFile)("tar", ["-xf", source, "-C", extracted]);
+
+const roots = (await readdir(extracted)).sort();
+if (roots.length !== 1) throw new Error(`FFmpeg archive must have one root directory; got ${roots.length}`);
+const upstream = join(extracted, roots[0]);
+for (const name of ["bin/ffmpeg", "bin/ffprobe", "lib", "LICENSE.txt"]) {
+ await mkdir(dirname(join(layer, name)), { recursive: true });
+ await cp(join(upstream, name), join(layer, name), {
+ recursive: true,
+ dereference: false,
+ // Node otherwise resolves copied links against the source tree and writes
+ // an absolute build-machine path. Such a Layer looks complete in `unzip
+ // -l` but its libraries cannot be found under /opt at runtime.
+ verbatimSymlinks: true,
+ });
+}
+
+const provenance = {
+ contract: "narratage.ffmpeg-lambda-layer@1",
+ ffmpegVersion: FFmpeg_VERSION,
+ architecture: "x86_64",
+ upstream: { url: SOURCE_URL, sha256: SOURCE_SHA256 },
+ paths: { ffmpeg: "/opt/bin/ffmpeg", ffprobe: "/opt/bin/ffprobe" },
+ license: "GPL-3.0-or-later",
+};
+await writeFile(join(layer, "narratage-layer.json"), `${JSON.stringify(provenance, null, 2)}\n`);
+await normalize(layer);
+
+const files = await entriesUnder(layer);
+for (const file of files) {
+ const info = await lstat(file);
+ if (!info.isSymbolicLink()) continue;
+ const target = await readlink(file);
+ if (isAbsolute(target)) throw new Error(`${relative(layer, file)} has an absolute symlink target: ${target}`);
+ const resolved = resolve(dirname(file), target);
+ const withinLayer = relative(layer, resolved);
+ if (withinLayer.startsWith("..") || isAbsolute(withinLayer)) {
+ throw new Error(`${relative(layer, file)} escapes the Layer: ${target}`);
+ }
+ await stat(resolved);
+}
+for (const binary of [join(layer, "bin/ffmpeg"), join(layer, "bin/ffprobe")]) {
+ const magic = await readFile(binary);
+ if (magic.length < 20 || !magic.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46]))) {
+ throw new Error(`${relative(layer, binary)} is not an ELF binary`);
+ }
+ if (magic.readUInt16LE(18) !== 62) throw new Error(`${relative(layer, binary)} is not x86-64`);
+}
+
+await promisify(execFile)("zip", [
+ "-X", "-q", "-y", archive,
+ ...files.map((path) => relative(layer, path)),
+], { cwd: layer, env: { ...process.env, TZ: "UTC" } });
+
+let uncompressedBytes = 0;
+for (const file of files) uncompressedBytes += (await lstat(file)).size;
+const archiveBytes = (await stat(archive)).size;
+const archiveSha256 = await sha256(archive);
+const artifact = {
+ ...provenance,
+ archiveSha256,
+ archiveBytes,
+ uncompressedBytes,
+ entryCount: files.length,
+};
+await writeFile(manifestPath, `${JSON.stringify(artifact, null, 2)}\n`);
+await rm(work, { recursive: true, force: true });
+process.stdout.write(`${JSON.stringify(artifact, null, 2)}\n`);
diff --git a/services/media-lambda/build.mjs b/services/media-lambda/build.mjs
index a34e24a6..1197462a 100755
--- a/services/media-lambda/build.mjs
+++ b/services/media-lambda/build.mjs
@@ -11,7 +11,6 @@ import { build } from "esbuild";
const root = dirname(fileURLToPath(import.meta.url));
const out = join(root, "build");
-await rm(out, { recursive: true, force: true });
await mkdir(out, { recursive: true });
const deployment = {
@@ -22,9 +21,17 @@ const deployment = {
ffmpegVersion: "8.0.1",
ffmpegPath: "/opt/bin/ffmpeg",
ffprobePath: "/opt/bin/ffprobe",
+ ffmpegLibraryPath: "/opt/lib",
};
const entry = join(out, "index.mjs");
const archive = join(out, "function.zip");
+for (const path of [
+ entry,
+ archive,
+ join(out, "deployment.json"),
+ join(out, "bundle-hash.txt"),
+ join(out, "function-artifact.json"),
+]) await rm(path, { force: true });
const result = await build({
entryPoints: [join(root, "src/handler.ts")],
@@ -57,10 +64,20 @@ await promisify(execFile)("zip", ["-X", "-q", "-j", archive, entry], {
env: { ...process.env, TZ: "UTC" },
});
const archiveStat = await stat(archive);
+const archiveBytes = await readFile(archive);
+const archiveSha256 = createHash("sha256").update(archiveBytes).digest();
+const functionArtifact = {
+ contract: "narratage.media-lambda-function-artifact@1",
+ bundleHash: hash,
+ archiveSha256: archiveSha256.toString("hex"),
+ codeSha256: archiveSha256.toString("base64"),
+ archiveBytes: archiveStat.size,
+};
+await writeFile(join(out, "function-artifact.json"),
+ `${JSON.stringify(functionArtifact, null, 2)}\n`);
process.stdout.write(`${JSON.stringify({
- bundleHash: hash,
+ ...functionArtifact,
bundleBytes: bundle.byteLength,
- archiveBytes: archiveStat.size,
deployment,
}, null, 2)}\n`);
diff --git a/services/media-lambda/canary.ts b/services/media-lambda/canary.ts
new file mode 100644
index 00000000..f0b93436
--- /dev/null
+++ b/services/media-lambda/canary.ts
@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import { AwsS3ObjectClient, S3ArtifactStore } from "@narratage/artifact-store-s3";
+import {
+ sealRenderedVisual,
+ verifyMediaInspection,
+ verifyMuxedMedia,
+ verifySynchronizedMedia,
+ verifyTimelineAudio,
+} from "@narratage/media";
+import type {
+ MediaInspection,
+ MuxedMedia,
+ SynchronizedMedia,
+ TimelineAudio,
+} from "@narratage/media";
+import {
+ sealAudioProgramPlan,
+ sealMediaSelectionRequest,
+ selectMediaStreams,
+} from "@narratage/media-pipeline";
+import type { MediaLambdaOperation } from "@narratage/provider-media-aws-lambda";
+import {
+ parseMediaLambdaResponse,
+ sealMediaLambdaRequest,
+} from "@narratage/provider-media-aws-lambda";
+import type { CanonicalValue } from "@narratage/protocol";
+import {
+ assertSpeechEvidenceAudioIdentity,
+ speechEvidenceSampleBoundary,
+} from "@narratage/speech";
+import type { SpeechEvidenceAudio } from "@narratage/speech";
+import { AwsLambdaJsonInvoker } from "@narratage/transport-aws-lambda";
+
+const run = promisify(execFile);
+const functionArn = process.env.NARRATAGE_MEDIA_FUNCTION_ARN;
+const bucket = process.env.NARRATAGE_MEDIA_ARTIFACT_BUCKET;
+const region = process.env.AWS_REGION;
+if (functionArn === undefined || bucket === undefined || region === undefined) {
+ throw new Error("set NARRATAGE_MEDIA_FUNCTION_ARN, NARRATAGE_MEDIA_ARTIFACT_BUCKET and AWS_REGION");
+}
+if (!/:\d+$/u.test(functionArn)) throw new Error("canary requires an immutable numeric function version ARN");
+
+const prefix = process.env.NARRATAGE_MEDIA_CANARY_PREFIX
+ ?? `canary/media-lambda/${new Date().toISOString().replaceAll(/[^0-9A-Za-z]/gu, "-")}`;
+const store = new S3ArtifactStore({
+ client: new AwsS3ObjectClient({ region }),
+ bucket,
+ prefix,
+ expectedBucketOwner: functionArn.split(":")[4],
+});
+const invoker = new AwsLambdaJsonInvoker({ functionName: functionArn, region });
+
+async function invoke(operation: MediaLambdaOperation, constraints: CanonicalValue): Promise<CanonicalValue> {
+ const reply = parseMediaLambdaResponse(await invoker.invoke(sealMediaLambdaRequest({
+ contract: "svml.media-lambda-request@1",
+ operation,
+ artifacts: { bucket, prefix },
+ constraints,
+ })));
+ if (!reply.ok) throw new Error(`${operation} failed (${reply.code}): ${reply.message}`);
+ return reply.value;
+}
+
+async function main() {
+ const work = await mkdtemp(join(tmpdir(), "narratage-media-canary-"));
+ try {
+ const sourcePath = join(work, "source.mp4");
+ await run(process.env.NARRATAGE_CANARY_FFMPEG ?? "ffmpeg", [
+ "-v", "error", "-y",
+ "-f", "lavfi", "-i", "testsrc2=s=160x96:r=24:d=1",
+ "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=32000:duration=1.05",
+ "-map", "0:v:0", "-map", "1:a:0",
+ "-c:v", "libx264", "-pix_fmt", "yuv420p",
+ "-c:a", "aac", sourcePath,
+ ], { timeout: 30_000 });
+ const source = await store.put(await readFile(sourcePath), "video/mp4");
+
+ const inspection = await invoke("inspect", {
+ contract: "svml.inspect-media-request@1",
+ source,
+ }) as unknown as MediaInspection;
+ verifyMediaInspection(inspection);
+ const selectionRequest = sealMediaSelectionRequest({
+ contract: "svml.media-selection-request@1",
+ video: { mode: "primary-moving" },
+ audio: { mode: "default" },
+ spanAuthority: "video",
+ frameRate: { numerator: 30, denominator: 1 },
+ });
+ const selection = selectMediaStreams(inspection, selectionRequest);
+
+ const synchronized = await invoke("normalize", {
+ contract: "svml.normalize-media-request@1",
+ source,
+ inspection,
+ selection,
+ frameRate: selectionRequest.frameRate,
+ audio: { sampleRate: 48_000, channels: 2, codec: "pcm_s16le", loudness: "preserve" },
+ }) as unknown as SynchronizedMedia;
+ verifySynchronizedMedia(synchronized);
+ assert(synchronized.visual !== undefined && synchronized.audio !== undefined);
+
+ const durationSec = synchronized.timeline.sampleFrames / 48_000;
+ const evidence = await invoke("project-speech-evidence-audio", {
+ contract: "svml.project-speech-evidence-audio-request@1",
+ source: synchronized.audio.artifact,
+ sourceSampleRate: 48_000,
+ sourceChannels: 2,
+ sourceCodec: "pcm_s16le",
+ sourceSampleFrames: synchronized.audio.sampleFrames,
+ evidenceSampleRate: 16_000,
+ evidenceChannels: 1,
+ evidenceCodec: "pcm_s16le",
+ evidenceSampleFrames: speechEvidenceSampleBoundary(synchronized.audio.sampleFrames),
+ durationSec,
+ segments: [{ segmentId: "canary", startSec: 0, endSec: durationSec }],
+ }) as unknown as SpeechEvidenceAudio;
+ assertSpeechEvidenceAudioIdentity(evidence);
+
+ const plan = sealAudioProgramPlan({
+ contract: "svml.audio-program-plan@1",
+ frameRate: synchronized.timeline.frameRate,
+ frameCount: synchronized.timeline.frameCount,
+ sampleRate: 48_000,
+ sampleFrames: synchronized.timeline.sampleFrames,
+ clips: [{
+ id: "canary:source",
+ artifact: synchronized.audio.artifact,
+ targetStartSample: 0,
+ targetEndSampleExclusive: synchronized.timeline.sampleFrames,
+ sourceStartSample: 0,
+ playbackRate: 1,
+ gain: 1,
+ fadeInSamples: 0,
+ fadeOutSamples: 0,
+ bus: "source",
+ }],
+ mix: { normalize: false, limiter: "none" },
+ });
+ const audio = await invoke("render-audio", {
+ contract: "svml.render-audio-request@1",
+ plan,
+ }) as unknown as TimelineAudio;
+ verifyTimelineAudio(audio);
+
+ const visual = sealRenderedVisual({
+ contract: "svml.rendered-visual@1",
+ frameRate: synchronized.visual.frameRate,
+ frameCount: synchronized.visual.frameCount,
+ canvas: { width: synchronized.visual.width, height: synchronized.visual.height },
+ artifact: synchronized.visual.artifact,
+ muted: true,
+ });
+ const muxed = await invoke("mux", {
+ contract: "svml.mux-media-request@1",
+ visual,
+ audio,
+ }) as unknown as MuxedMedia;
+ verifyMuxedMedia(muxed);
+
+ const finalInspection = await invoke("inspect", {
+ contract: "svml.inspect-media-request@1",
+ source: muxed.artifact,
+ }) as unknown as MediaInspection;
+ verifyMediaInspection(finalInspection);
+ assert.equal(finalInspection.streams.filter((stream) => stream.kind === "video").length, 1);
+ assert.equal(finalInspection.streams.filter((stream) => stream.kind === "audio").length, 1);
+
+ process.stdout.write(`${JSON.stringify({
+ functionArn,
+ prefix,
+ source: source.digest,
+ normalized: {
+ frameCount: synchronized.timeline.frameCount,
+ sampleFrames: synchronized.timeline.sampleFrames,
+ visual: synchronized.visual.artifact.digest,
+ audio: synchronized.audio.artifact.digest,
+ },
+ evidence: evidence.artifact.digest,
+ timelineAudio: audio.artifact.digest,
+ muxed: muxed.artifact.digest,
+ finalStreams: finalInspection.streams.map((stream) => ({
+ index: stream.index,
+ kind: stream.kind,
+ codec: stream.codecName,
+ decodedUnits: stream.decodedUnitCount,
+ })),
+ }, null, 2)}\n`);
+ } finally {
+ await rm(work, { recursive: true, force: true });
+ if (process.env.NARRATAGE_MEDIA_CANARY_KEEP !== "1" && store.list !== undefined && store.delete !== undefined) {
+ for (const digest of await store.list()) await store.delete(digest);
+ }
+ }
+}
+
+await main();
diff --git a/services/media-lambda/deploy.sh b/services/media-lambda/deploy.sh
new file mode 100755
index 00000000..05a82e98
--- /dev/null
+++ b/services/media-lambda/deploy.sh
@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# Plan or apply the complete, long-lived Media Lambda CloudFormation stack.
+set -euo pipefail
+
+operation="${1:-}"
+if [ "$operation" != plan ] && [ "$operation" != apply ]; then
+ printf 'usage: %s plan | %s apply <change-set-arn>\n' "$0" "$0" >&2
+ exit 2
+fi
+
+: "${AWS_REGION:?set AWS_REGION, e.g. us-east-1}"
+: "${AWS_ACCOUNT_ID:?set AWS_ACCOUNT_ID, your 12-digit account id}"
+: "${NARRATAGE_MEDIA_ENVIRONMENT:?set NARRATAGE_MEDIA_ENVIRONMENT, e.g. dev}"
+: "${NARRATAGE_MEDIA_STACK:?set NARRATAGE_MEDIA_STACK, e.g. narratage-media-dev}"
+
+here="$(cd "$(dirname "$0")" && pwd)"
+caller_account="$(aws sts get-caller-identity --query Account --output text)"
+if [ "$caller_account" != "$AWS_ACCOUNT_ID" ]; then
+ printf 'AWS credential chain resolves account %s, not configured account %s\n' \
+ "$caller_account" "$AWS_ACCOUNT_ID" >&2
+ exit 2
+fi
+
+if [ "$operation" = apply ]; then
+ change_set="${2:?apply requires the exact change-set ARN printed by plan}"
+ stack="$(aws cloudformation describe-change-set --region "$AWS_REGION" \
+ --change-set-name "$change_set" --query StackName --output text)"
+ if [ "$stack" != "$NARRATAGE_MEDIA_STACK" ]; then
+ printf 'change set belongs to %s, not configured stack %s\n' "$stack" "$NARRATAGE_MEDIA_STACK" >&2
+ exit 2
+ fi
+ stack_status="$(aws cloudformation describe-stacks --region "$AWS_REGION" \
+ --stack-name "$stack" --query 'Stacks[0].StackStatus' --output text)"
+ aws cloudformation execute-change-set --region "$AWS_REGION" --change-set-name "$change_set"
+ if [ "$stack_status" = REVIEW_IN_PROGRESS ]; then
+ aws cloudformation wait stack-create-complete --region "$AWS_REGION" --stack-name "$stack"
+ else
+ aws cloudformation wait stack-update-complete --region "$AWS_REGION" --stack-name "$stack"
+ fi
+ aws cloudformation describe-stacks --region "$AWS_REGION" --stack-name "$stack" \
+ --query 'Stacks[0].Outputs[].{Key:OutputKey,Value:OutputValue}' --output table
+ exit 0
+fi
+
+: "${NARRATAGE_MEDIA_ARTIFACT_BUCKET:?set NARRATAGE_MEDIA_ARTIFACT_BUCKET}"
+: "${NARRATAGE_MEDIA_DEPLOYMENT_BUCKET:?set NARRATAGE_MEDIA_DEPLOYMENT_BUCKET}"
+: "${NARRATAGE_MEDIA_FUNCTION:?set NARRATAGE_MEDIA_FUNCTION}"
+: "${NARRATAGE_MEDIA_ROLE:?set NARRATAGE_MEDIA_ROLE}"
+: "${NARRATAGE_MEDIA_LAYER:?set NARRATAGE_MEDIA_LAYER}"
+
+memory="${NARRATAGE_MEDIA_MEMORY:-3008}"
+ephemeral="${NARRATAGE_MEDIA_EPHEMERAL:-8192}"
+concurrency="${NARRATAGE_MEDIA_CONCURRENCY:-8}"
+retention="${NARRATAGE_MEDIA_LOG_RETENTION_DAYS:-14}"
+
+printf 'Building immutable function and FFmpeg Layer artifacts\n'
+(cd "$here" && node build.mjs)
+(cd "$here" && node build-layer.mjs)
+
+function_hash="$(node -p "require('$here/build/function-artifact.json').archiveSha256")"
+function_code_sha="$(node -p "require('$here/build/function-artifact.json').codeSha256")"
+bundle_hash="$(node -p "require('$here/build/function-artifact.json').bundleHash")"
+layer_hash="$(node -p "require('$here/build/ffmpeg-layer-artifact.json').archiveSha256")"
+function_key="narratage/media-lambda/functions/${function_hash}.zip"
+layer_key="narratage/media-lambda/layers/${layer_hash}.zip"
+
+uncompressed_layer="$(node -p "require('$here/build/ffmpeg-layer-artifact.json').uncompressedBytes")"
+uncompressed_function="$(unzip -l "$here/build/function.zip" | awk 'END {print $1}')"
+if [ "$((uncompressed_layer + uncompressed_function))" -ge 262144000 ]; then
+ printf 'function plus Layer exceed Lambda uncompressed ZIP quota\n' >&2
+ exit 1
+fi
+
+printf 'Uploading content-addressed deployment artifacts\n'
+aws s3 cp "$here/build/function.zip" \
+ "s3://${NARRATAGE_MEDIA_DEPLOYMENT_BUCKET}/${function_key}" \
+ --region "$AWS_REGION" --only-show-errors --checksum-algorithm SHA256
+aws s3 cp "$here/build/ffmpeg-layer.zip" \
+ "s3://${NARRATAGE_MEDIA_DEPLOYMENT_BUCKET}/${layer_key}" \
+ --region "$AWS_REGION" --only-show-errors --checksum-algorithm SHA256
+
+stack_status="$(aws cloudformation describe-stacks --region "$AWS_REGION" \
+ --stack-name "$NARRATAGE_MEDIA_STACK" --query 'Stacks[0].StackStatus' --output text 2>/dev/null || true)"
+if [ -z "$stack_status" ] || [ "$stack_status" = REVIEW_IN_PROGRESS ]; then
+ change_set_type=CREATE
+else
+ change_set_type=UPDATE
+fi
+change_set_name="media-$(date -u +%Y%m%dT%H%M%SZ)-${function_hash:0:8}-${layer_hash:0:8}"
+
+printf 'Creating unexecuted %s Change Set %s\n' "$change_set_type" "$change_set_name"
+change_set_arn="$(aws cloudformation create-change-set --region "$AWS_REGION" \
+ --stack-name "$NARRATAGE_MEDIA_STACK" \
+ --change-set-name "$change_set_name" \
+ --change-set-type "$change_set_type" \
+ --description "Narratage media function ${function_hash}; layer ${layer_hash}" \
+ --template-body "file://${here}/template.yaml" \
+ --capabilities CAPABILITY_NAMED_IAM \
+ --parameters \
+ "ParameterKey=EnvironmentName,ParameterValue=${NARRATAGE_MEDIA_ENVIRONMENT}" \
+ "ParameterKey=FunctionName,ParameterValue=${NARRATAGE_MEDIA_FUNCTION}" \
+ "ParameterKey=ExecutionRoleName,ParameterValue=${NARRATAGE_MEDIA_ROLE}" \
+ "ParameterKey=LayerName,ParameterValue=${NARRATAGE_MEDIA_LAYER}" \
+ "ParameterKey=ArtifactBucket,ParameterValue=${NARRATAGE_MEDIA_ARTIFACT_BUCKET}" \
+ "ParameterKey=DeploymentBucket,ParameterValue=${NARRATAGE_MEDIA_DEPLOYMENT_BUCKET}" \
+ "ParameterKey=FunctionCodeKey,ParameterValue=${function_key}" \
+ "ParameterKey=FunctionCodeSha256,ParameterValue=${function_code_sha}" \
+ "ParameterKey=FunctionBundleHash,ParameterValue=${bundle_hash}" \
+ "ParameterKey=LayerCodeKey,ParameterValue=${layer_key}" \
+ "ParameterKey=LayerArchiveHash,ParameterValue=${layer_hash}" \
+ "ParameterKey=MemorySize,ParameterValue=${memory}" \
+ "ParameterKey=EphemeralStorageSize,ParameterValue=${ephemeral}" \
+ "ParameterKey=ReservedConcurrency,ParameterValue=${concurrency}" \
+ "ParameterKey=LogRetentionDays,ParameterValue=${retention}" \
+ --query Id --output text)"
+printf 'Created %s\n' "$change_set_arn"
+
+if ! aws cloudformation wait change-set-create-complete --region "$AWS_REGION" \
+ --change-set-name "$change_set_arn"; then
+ aws cloudformation describe-change-set --region "$AWS_REGION" \
+ --change-set-name "$change_set_arn" \
+ --query '{Status:Status,Reason:StatusReason}' --output json >&2
+ exit 1
+fi
+
+aws cloudformation describe-change-set --region "$AWS_REGION" \
+ --change-set-name "$change_set_arn" \
+ --query '{Stack:StackName,Status:Status,ExecutionStatus:ExecutionStatus,Changes:Changes[].ResourceChange.{Action:Action,LogicalId:LogicalResourceId,Type:ResourceType,Replacement:Replacement}}' \
+ --output json
+printf '\nReview the change set above, then apply exactly:\n\n'
+printf ' %q apply %q\n' "$0" "$change_set_arn"
diff --git a/services/media-lambda/iam/execution-trust.json b/services/media-lambda/iam/execution-trust.json
deleted file mode 100644
index 75acf2c0..00000000
--- a/services/media-lambda/iam/execution-trust.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
- "Version": "2012-10-17",
- "Statement": [
- {
- "Effect": "Allow",
- "Principal": { "Service": "lambda.amazonaws.com" },
- "Action": "sts:AssumeRole"
- }
- ]
-}
diff --git a/services/media-lambda/iam/execution.json b/services/media-lambda/iam/execution.json
deleted file mode 100644
index d3c29156..00000000
--- a/services/media-lambda/iam/execution.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
- "Version": "2012-10-17",
- "Statement": [
- {
- "Sid": "ReadSourcesAndWriteResults",
- "Effect": "Allow",
- "Action": ["s3:GetObject", "s3:PutObject"],
- "Resource": "arn:aws:s3:::BUCKET/*"
- },
- {
- "Sid": "SayWhatHappened",
- "Effect": "Allow",
- "Action": ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
- "Resource": "arn:aws:logs:REGION:ACCOUNT_ID:*"
- }
- ]
-}
diff --git a/services/media-lambda/iam/publisher.json b/services/media-lambda/iam/publisher.json
index c9c5c32e..10360510 100644
--- a/services/media-lambda/iam/publisher.json
+++ b/services/media-lambda/iam/publisher.json
@@ -2,10 +2,13 @@
"Version": "2012-10-17",
"Statement": [
{
- "Sid": "ReadThePinnedFfmpegLayer",
+ "Sid": "ManageThePinnedFfmpegLayer",
"Effect": "Allow",
- "Action": ["lambda:GetLayerVersion"],
- "Resource": "arn:aws:lambda:REGION:*:layer:*:*"
+ "Action": ["lambda:PublishLayerVersion", "lambda:GetLayerVersion"],
+ "Resource": [
+ "arn:aws:lambda:REGION:ACCOUNT_ID:layer:narratage-ffmpeg-8-0-1",
+ "arn:aws:lambda:REGION:ACCOUNT_ID:layer:narratage-ffmpeg-8-0-1:*"
+ ]
},
{
"Sid": "PublishTheFunction",
@@ -14,18 +17,61 @@
"lambda:CreateFunction",
"lambda:GetFunction",
"lambda:GetFunctionConfiguration",
+ "lambda:GetFunctionConcurrency",
+ "lambda:GetRuntimeManagementConfig",
"lambda:InvokeFunction",
+ "lambda:ListTags",
+ "lambda:ListVersionsByFunction",
"lambda:PublishVersion",
+ "lambda:PutRuntimeManagementConfig",
"lambda:UpdateFunctionCode",
- "lambda:UpdateFunctionConfiguration"
+ "lambda:UpdateFunctionConfiguration",
+ "lambda:DeleteFunction",
+ "lambda:PutFunctionConcurrency",
+ "lambda:TagResource",
+ "lambda:UntagResource"
],
"Resource": "arn:aws:lambda:REGION:ACCOUNT_ID:function:narratage-media*"
},
{
"Sid": "HandTheExecutionRoleToTheFunction",
"Effect": "Allow",
- "Action": ["iam:PassRole"],
- "Resource": "arn:aws:iam::ACCOUNT_ID:role/NarratageMediaExecution"
+ "Action": [
+ "iam:CreateRole",
+ "iam:GetRole",
+ "iam:PutRolePolicy",
+ "iam:DeleteRolePolicy",
+ "iam:DeleteRole",
+ "iam:PassRole",
+ "iam:TagRole",
+ "iam:UntagRole"
+ ],
+ "Resource": "arn:aws:iam::ACCOUNT_ID:role/NarratageMediaExecution-*"
+ },
+ {
+ "Sid": "ManageTheMediaStack",
+ "Effect": "Allow",
+ "Action": [
+ "cloudformation:CreateStack",
+ "cloudformation:UpdateStack",
+ "cloudformation:CreateChangeSet",
+ "cloudformation:DescribeStacks",
+ "cloudformation:DescribeStackEvents",
+ "cloudformation:DescribeChangeSet",
+ "cloudformation:ExecuteChangeSet",
+ "cloudformation:DeleteChangeSet"
+ ],
+ "Resource": "arn:aws:cloudformation:REGION:ACCOUNT_ID:stack/narratage-media-*/*"
+ },
+ {
+ "Sid": "ManageTheMediaLogGroup",
+ "Effect": "Allow",
+ "Action": [
+ "logs:CreateLogGroup",
+ "logs:DeleteLogGroup",
+ "logs:PutRetentionPolicy"
+ ],
+ "Resource": "arn:aws:logs:REGION:ACCOUNT_ID:log-group:/aws/lambda/narratage-media-*"
},
{
"Sid": "TheArtifactStore",
@@ -33,7 +79,9 @@
"Action": ["s3:GetObject", "s3:PutObject", "s3:ListBucket", "s3:DeleteObject"],
"Resource": [
"arn:aws:s3:::BUCKET",
- "arn:aws:s3:::BUCKET/*"
+ "arn:aws:s3:::BUCKET/*",
+ "arn:aws:s3:::DEPLOYMENT_BUCKET",
+ "arn:aws:s3:::DEPLOYMENT_BUCKET/narratage/media-lambda/*"
]
}
]
diff --git a/services/media-lambda/package.json b/services/media-lambda/package.json
index de2731a2..7821e815 100644
--- a/services/media-lambda/package.json
+++ b/services/media-lambda/package.json
@@ -8,12 +8,18 @@
},
"dependencies": {
"@narratage/artifact-store-s3": "workspace:*",
+ "@narratage/media": "workspace:*",
"@narratage/media-execution": "workspace:*",
+ "@narratage/media-pipeline": "workspace:*",
"@narratage/protocol": "workspace:*",
- "@narratage/provider-media-aws-lambda": "workspace:*"
+ "@narratage/provider-media-aws-lambda": "workspace:*",
+ "@narratage/speech": "workspace:*",
+ "@narratage/transport-aws-lambda": "workspace:*"
},
"scripts": {
- "build": "node build.mjs"
+ "build": "node build.mjs",
+ "build:layer": "node build-layer.mjs",
+ "canary": "node --import tsx canary.ts"
},
"devDependencies": {
"esbuild": "^0.25.0"
diff --git a/services/media-lambda/publish.sh b/services/media-lambda/publish.sh
deleted file mode 100755
index d84ccf43..00000000
--- a/services/media-lambda/publish.sh
+++ /dev/null
@@ -1,111 +0,0 @@
-#!/usr/bin/env bash
-# Publish one immutable managed-runtime ZIP of the media function.
-#
-# FFmpeg is a separate, immutable Layer. This script never builds an image,
-# creates an ECR repository or guesses which Layer an account should trust.
-set -euo pipefail
-
-: "${AWS_REGION:?set AWS_REGION, e.g. us-east-1}"
-: "${AWS_ACCOUNT_ID:?set AWS_ACCOUNT_ID, your 12-digit account id}"
-: "${NARRATAGE_MEDIA_BUCKET:?set NARRATAGE_MEDIA_BUCKET, the ArtifactStore bucket the function shares}"
-: "${NARRATAGE_FFMPEG_LAYER_ARN:?set NARRATAGE_FFMPEG_LAYER_ARN to an immutable layer version ARN}"
-
-FUNCTION="${NARRATAGE_MEDIA_FUNCTION:-narratage-media-zip}"
-ROLE="${NARRATAGE_MEDIA_ROLE:-NarratageMediaExecution}"
-MEMORY="${NARRATAGE_MEDIA_MEMORY:-3008}"
-TIMEOUT="${NARRATAGE_MEDIA_TIMEOUT:-900}"
-EPHEMERAL="${NARRATAGE_MEDIA_EPHEMERAL:-8192}"
-FFMPEG_VERSION="8.0.1"
-
-here="$(cd "$(dirname "$0")" && pwd)"
-layer="$NARRATAGE_FFMPEG_LAYER_ARN"
-if [[ ! "$layer" =~ ^arn:aws[a-zA-Z-]*:lambda:([a-z0-9-]+):([0-9]{12}):layer:[A-Za-z0-9-_]+:([0-9]+)$ ]]; then
- printf 'NARRATAGE_FFMPEG_LAYER_ARN must name an immutable Layer version; got %s\n' "$layer" >&2
- exit 2
-fi
-if [ "${BASH_REMATCH[1]}" != "$AWS_REGION" ]; then
- printf 'FFmpeg Layer belongs to region %s, not configured region %s\n' \
- "${BASH_REMATCH[1]}" "$AWS_REGION" >&2
- exit 2
-fi
-
-printf 'Bundling managed-runtime function ZIP\n'
-(cd "$here" && node build.mjs >/dev/null)
-hash="$(tr -d '\n' < "$here/build/bundle-hash.txt")"
-runtime="$(node -p "require('$here/build/deployment.json').runtime")"
-architecture="$(node -p "require('$here/build/deployment.json').architecture")"
-handler="$(node -p "require('$here/build/deployment.json').handler")"
-archive="$here/build/function.zip"
-
-# Resolve the exact Layer before mutating the function. The ARN is immutable;
-# runtime validation then proves that /opt/bin really contains the promised
-# pair rather than trusting its name.
-aws lambda get-layer-version-by-arn --region "$AWS_REGION" --arn "$layer" >/dev/null
-
-node -e 'const fs=require("node:fs");fs.writeFileSync(process.argv[1],JSON.stringify({Variables:{NARRATAGE_MEDIA_BUNDLE_HASH:process.argv[2],NARRATAGE_FFMPEG_VERSION:process.argv[3],FFMPEG_PATH:"/opt/bin/ffmpeg",FFPROBE_PATH:"/opt/bin/ffprobe"}}))' \
- "$here/build/environment.json" "$hash" "$FFMPEG_VERSION"
-
-printf 'Publishing bundle %s with Layer %s\n' "$hash" "$layer"
-if aws lambda get-function --region "$AWS_REGION" --function-name "$FUNCTION" >/dev/null 2>&1; then
- package_type="$(aws lambda get-function-configuration --region "$AWS_REGION" \
- --function-name "$FUNCTION" --query PackageType --output text)"
- if [ "$package_type" != Zip ]; then
- printf '%s is a %s function; AWS cannot change package type. Set NARRATAGE_MEDIA_FUNCTION to a new name.\n' \
- "$FUNCTION" "$package_type" >&2
- exit 2
- fi
- aws lambda update-function-code --region "$AWS_REGION" --function-name "$FUNCTION" \
- --zip-file "fileb://$archive" --architectures "$architecture" >/dev/null
- aws lambda wait function-updated-v2 --region "$AWS_REGION" --function-name "$FUNCTION"
- aws lambda update-function-configuration --region "$AWS_REGION" --function-name "$FUNCTION" \
- --role "arn:aws:iam::${AWS_ACCOUNT_ID}:role/${ROLE}" \
- --runtime "$runtime" --handler "$handler" --layers "$layer" \
- --memory-size "$MEMORY" --timeout "$TIMEOUT" \
- --ephemeral-storage "Size=${EPHEMERAL}" \
- --environment "file://$here/build/environment.json" >/dev/null
- aws lambda wait function-updated-v2 --region "$AWS_REGION" --function-name "$FUNCTION"
-else
- aws lambda create-function --region "$AWS_REGION" --function-name "$FUNCTION" \
- --runtime "$runtime" --handler "$handler" \
- --zip-file "fileb://$archive" \
- --role "arn:aws:iam::${AWS_ACCOUNT_ID}:role/${ROLE}" \
- --architectures "$architecture" --layers "$layer" \
- --memory-size "$MEMORY" --timeout "$TIMEOUT" \
- --ephemeral-storage "Size=${EPHEMERAL}" \
- --environment "file://$here/build/environment.json" >/dev/null
- aws lambda wait function-active-v2 --region "$AWS_REGION" --function-name "$FUNCTION"
-fi
-
-read -r actual_runtime actual_handler actual_architecture actual_layer layer_count actual_hash actual_ffmpeg package_type < <(
- aws lambda get-function-configuration --region "$AWS_REGION" --function-name "$FUNCTION" \
- --query '[Runtime,Handler,Architectures[0],Layers[0].Arn,length(Layers),Environment.Variables.NARRATAGE_MEDIA_BUNDLE_HASH,Environment.Variables.NARRATAGE_FFMPEG_VERSION,PackageType]' \
- --output text
-)
-if [ "$actual_runtime" != "$runtime" ] || [ "$actual_handler" != "$handler" ] \
- || [ "$actual_architecture" != "$architecture" ] || [ "$actual_layer" != "$layer" ] \
- || [ "$layer_count" != 1 ] || [ "$actual_hash" != "$hash" ] \
- || [ "$actual_ffmpeg" != "$FFMPEG_VERSION" ] || [ "$package_type" != Zip ]; then
- printf 'published function configuration does not match the reviewed deployment\n' >&2
- exit 1
-fi
-
-# A version, not $LATEST. The Provider refuses an unqualified ARN.
-version="$(aws lambda publish-version --region "$AWS_REGION" --function-name "$FUNCTION" \
- --description "bundle ${hash}; ffmpeg layer ${layer}" --query Version --output text)"
-arn="arn:aws:lambda:${AWS_REGION}:${AWS_ACCOUNT_ID}:function:${FUNCTION}:${version}"
-
-cat <<JSON
-
-Published. Add this to the endpoints of your Runtime Profile:
-
- {
- "use": "@narratage/provider-media-aws-lambda",
- "instance": "media.aws-lambda",
- "lane": "media",
- "config": {
- "functionArn": "${arn}",
- "bucket": "${NARRATAGE_MEDIA_BUCKET}"
- }
- }
-
-JSON
diff --git a/services/media-lambda/src/handler.ts b/services/media-lambda/src/handler.ts
index 3d4b20f6..50e54769 100644
--- a/services/media-lambda/src/handler.ts
+++ b/services/media-lambda/src/handler.ts
@@ -40,6 +40,7 @@ const OPERATIONS: Record<
const FFMPEG_PATH = process.env.FFMPEG_PATH ?? "/opt/bin/ffmpeg";
const FFPROBE_PATH = process.env.FFPROBE_PATH ?? "/opt/bin/ffprobe";
+const FFMPEG_LIBRARY_PATH = process.env.NARRATAGE_FFMPEG_LIBRARY_PATH;
const run = promisify(execFile);
function positiveInteger(value: string | undefined, fallback: number): number {
@@ -99,6 +100,7 @@ export type MediaLambdaHandlerOptions = {
readonly client?: S3ObjectClient;
readonly ffmpegPath?: string;
readonly ffprobePath?: string;
+ readonly sharedLibraryPath?: string;
/**
* The deployed ZIP sets this to the version promised by its immutable Layer.
* Tests and embedded handlers may omit it when their binary identity is
@@ -112,11 +114,20 @@ function versionMatches(line: string, tool: "ffmpeg" | "ffprobe", expected: stri
return new RegExp(`^${tool} version (?:n)?${escaped}(?:[-\\s]|$)`, "u").test(line);
}
-async function assertBinaryVersion(path: string, tool: "ffmpeg" | "ffprobe", expected: string): Promise<void> {
+async function assertBinaryVersion(
+ path: string,
+ tool: "ffmpeg" | "ffprobe",
+ expected: string,
+ sharedLibraryPath?: string,
+): Promise<void> {
const { stdout } = await run(path, ["-version"], {
encoding: "utf8",
maxBuffer: 64 * 1024,
timeout: 10_000,
+ env: {
+ ...process.env,
+ ...(sharedLibraryPath === undefined ? {} : { LD_LIBRARY_PATH: sharedLibraryPath }),
+ },
});
const firstLine = stdout.split(/\r?\n/u, 1)[0] ?? "";
if (!versionMatches(firstLine, tool, expected)) {
@@ -128,11 +139,12 @@ async function assertBinaryPair(
ffmpegPath: string,
ffprobePath: string,
expected: string | undefined,
+ sharedLibraryPath?: string,
): Promise<void> {
if (expected === undefined) return;
await Promise.all([
- assertBinaryVersion(ffmpegPath, "ffmpeg", expected),
- assertBinaryVersion(ffprobePath, "ffprobe", expected),
+ assertBinaryVersion(ffmpegPath, "ffmpeg", expected, sharedLibraryPath),
+ assertBinaryVersion(ffprobePath, "ffprobe", expected, sharedLibraryPath),
]);
}
@@ -144,6 +156,7 @@ async function assertBinaryPair(
export function createMediaLambdaHandler(options: MediaLambdaHandlerOptions = {}) {
const ffmpegPath = options.ffmpegPath ?? FFMPEG_PATH;
const ffprobePath = options.ffprobePath ?? FFPROBE_PATH;
+ const sharedLibraryPath = options.sharedLibraryPath ?? FFMPEG_LIBRARY_PATH;
// One promise per warm execution environment. A missing or wrong Layer is a
// typed fulfillment failure, not a deployment fact silently discovered after
// several expensive transformations have already run.
@@ -157,12 +170,14 @@ export function createMediaLambdaHandler(options: MediaLambdaHandlerOptions = {}
ffmpegPath,
ffprobePath,
options.expectedFfmpegVersion ?? process.env.NARRATAGE_FFMPEG_VERSION,
+ sharedLibraryPath,
);
await binariesReady;
const env: MediaExecutionEnvironment = {
artifacts: gateway(request.artifacts, options.client ?? new AwsS3ObjectClient({})),
ffmpegPath,
ffprobePath,
+ ...(sharedLibraryPath === undefined ? {} : { sharedLibraryPath }),
processTimeoutMs: positiveInteger(process.env.SVML_MEDIA_TIMEOUT_MS, 14 * 60_000),
maxProbeOutputBytes: positiveInteger(process.env.SVML_MEDIA_MAX_PROBE_BYTES, 256 * 1024 * 1024),
label: "media.aws-lambda",
diff --git a/services/media-lambda/template.yaml b/services/media-lambda/template.yaml
new file mode 100644
index 00000000..38d80049
--- /dev/null
+++ b/services/media-lambda/template.yaml
@@ -0,0 +1,160 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: "Narratage media execution service: FFmpeg Layer, function, immutable version, role and logs."
+
+Parameters:
+ EnvironmentName:
+ Type: String
+ AllowedPattern: "[a-z0-9][a-z0-9-]{0,30}"
+ FunctionName:
+ Type: String
+ AllowedPattern: "[A-Za-z0-9-_]{1,64}"
+ ExecutionRoleName:
+ Type: String
+ AllowedPattern: "[A-Za-z0-9+=,.@_-]{1,64}"
+ LayerName:
+ Type: String
+ AllowedPattern: "[A-Za-z0-9-_]{1,140}"
+ ArtifactBucket:
+ Type: String
+ DeploymentBucket:
+ Type: String
+ FunctionCodeKey:
+ Type: String
+ FunctionCodeSha256:
+ Type: String
+ FunctionBundleHash:
+ Type: String
+ LayerCodeKey:
+ Type: String
+ LayerArchiveHash:
+ Type: String
+ MemorySize:
+ Type: Number
+ Default: 3008
+ MinValue: 1024
+ MaxValue: 10240
+ EphemeralStorageSize:
+ Type: Number
+ Default: 8192
+ MinValue: 512
+ MaxValue: 10240
+ ReservedConcurrency:
+ Type: Number
+ Default: 8
+ MinValue: 1
+ LogRetentionDays:
+ Type: Number
+ Default: 14
+ AllowedValues: [1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365]
+
+Resources:
+ MediaLogGroup:
+ Type: AWS::Logs::LogGroup
+ DeletionPolicy: RetainExceptOnCreate
+ UpdateReplacePolicy: Retain
+ Properties:
+ LogGroupName: !Sub "/aws/lambda/${FunctionName}"
+ RetentionInDays: !Ref LogRetentionDays
+
+ MediaExecutionRole:
+ Type: AWS::IAM::Role
+ Properties:
+ RoleName: !Ref ExecutionRoleName
+ Description: !Sub "Narratage media execution role for ${EnvironmentName}"
+ AssumeRolePolicyDocument:
+ Version: "2012-10-17"
+ Statement:
+ - Effect: Allow
+ Principal:
+ Service: lambda.amazonaws.com
+ Action: sts:AssumeRole
+ Policies:
+ - PolicyName: NarratageMediaArtifactsAndLogs
+ PolicyDocument:
+ Version: "2012-10-17"
+ Statement:
+ - Sid: ReadSourcesAndWriteResults
+ Effect: Allow
+ Action:
+ - s3:GetObject
+ - s3:PutObject
+ Resource: !Sub "arn:${AWS::Partition}:s3:::${ArtifactBucket}/*"
+ - Sid: WriteFunctionLogs
+ Effect: Allow
+ Action:
+ - logs:CreateLogStream
+ - logs:PutLogEvents
+ Resource: !Sub "arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/lambda/${FunctionName}:*"
+
+ MediaFfmpegLayer:
+ Type: AWS::Lambda::LayerVersion
+ DeletionPolicy: RetainExceptOnCreate
+ UpdateReplacePolicy: Retain
+ Properties:
+ LayerName: !Ref LayerName
+ Description: !Sub "FFmpeg 8.0.1 x86-64 GPL shared; archive sha256 ${LayerArchiveHash}"
+ Content:
+ S3Bucket: !Ref DeploymentBucket
+ S3Key: !Ref LayerCodeKey
+ CompatibleArchitectures:
+ - x86_64
+ CompatibleRuntimes:
+ - nodejs22.x
+ LicenseInfo: GPL-3.0-or-later
+
+ MediaFunction:
+ Type: AWS::Lambda::Function
+ DependsOn: MediaLogGroup
+ Properties:
+ FunctionName: !Ref FunctionName
+ Description: Narratage remote media execution
+ Runtime: nodejs22.x
+ RuntimeManagementConfig:
+ UpdateRuntimeOn: FunctionUpdate
+ Handler: index.handler
+ Architectures:
+ - x86_64
+ Role: !GetAtt MediaExecutionRole.Arn
+ Code:
+ S3Bucket: !Ref DeploymentBucket
+ S3Key: !Ref FunctionCodeKey
+ Layers:
+ - !Ref MediaFfmpegLayer
+ MemorySize: !Ref MemorySize
+ Timeout: 900
+ EphemeralStorage:
+ Size: !Ref EphemeralStorageSize
+ ReservedConcurrentExecutions: !Ref ReservedConcurrency
+ Environment:
+ Variables:
+ NARRATAGE_MEDIA_BUNDLE_HASH: !Ref FunctionBundleHash
+ NARRATAGE_FFMPEG_VERSION: "8.0.1"
+ FFMPEG_PATH: /opt/bin/ffmpeg
+ FFPROBE_PATH: /opt/bin/ffprobe
+ NARRATAGE_FFMPEG_LIBRARY_PATH: /opt/lib
+
+ MediaFunctionVersion:
+ Type: AWS::Lambda::Version
+ DeletionPolicy: RetainExceptOnCreate
+ UpdateReplacePolicy: Retain
+ Properties:
+ FunctionName: !Ref MediaFunction
+ CodeSha256: !Ref FunctionCodeSha256
+ Description: !Sub "function ${FunctionBundleHash}; layer ${LayerArchiveHash}"
+
+Outputs:
+ FunctionVersionArn:
+ Description: Immutable function ARN for @narratage/provider-media-aws-lambda.
+ Value: !Ref MediaFunctionVersion
+ LayerVersionArn:
+ Description: Immutable FFmpeg Layer version used by the function.
+ Value: !Ref MediaFfmpegLayer
+ ExecutionRoleArn:
+ Value: !GetAtt MediaExecutionRole.Arn
+ ArtifactBucketName:
+ Value: !Ref ArtifactBucket
+ RuntimeProfileEndpoint:
+ Description: Endpoint entry; parse this output as JSON.
+ Value: !Sub
+ - '{"use":"@narratage/provider-media-aws-lambda","instance":"media.aws-lambda.${EnvironmentName}","lane":"media","config":{"functionArn":"${FunctionVersionArn}","bucket":"${ArtifactBucket}","region":"${AWS::Region}","defaultConcurrency":${ReservedConcurrency}}}'
+ - FunctionVersionArn: !Ref MediaFunctionVersion
diff --git a/services/media-lambda/test/deployment.test.ts b/services/media-lambda/test/deployment.test.ts
new file mode 100644
index 00000000..120a5b28
--- /dev/null
+++ b/services/media-lambda/test/deployment.test.ts
@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const service = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+test("the stack owns the complete service without granting media semantics extra authority", async () => {
+ const template = await readFile(join(service, "template.yaml"), "utf8");
+ for (const resource of [
+ "AWS::Logs::LogGroup",
+ "AWS::IAM::Role",
+ "AWS::Lambda::LayerVersion",
+ "AWS::Lambda::Function",
+ "AWS::Lambda::Version",
+ ]) assert.equal(template.includes(resource), true, `${resource} is absent from the stack`);
+
+ assert.match(template, /s3:GetObject[\s\S]*s3:PutObject/u);
+ assert.doesNotMatch(template, /Action:\s*["']?s3:\*/u);
+ assert.doesNotMatch(template, /Resource:\s*["']?\*["']?/u);
+ assert.match(template, /ReservedConcurrentExecutions: !Ref ReservedConcurrency/u);
+ assert.match(template, /UpdateRuntimeOn: FunctionUpdate/u);
+ assert.match(template, /NARRATAGE_FFMPEG_LIBRARY_PATH: \/opt\/lib/u);
+ assert.equal((template.match(/DeletionPolicy: RetainExceptOnCreate/gu) ?? []).length, 3);
+ assert.equal((template.match(/UpdateReplacePolicy: Retain/gu) ?? []).length, 3);
+ assert.match(template, /FunctionVersionArn:[\s\S]*MediaFunctionVersion/u);
+ assert.doesNotMatch(template, /!Join \[":", \[!GetAtt MediaFunction\.Arn/u);
+});
+
+test("deployment separates reviewable planning from exact change-set execution", async () => {
+ const script = await readFile(join(service, "deploy.sh"), "utf8");
+ assert.match(script, /operation[^\n]+plan/u);
+ assert.match(script, /operation[^\n]+apply/u);
+ assert.match(script, /cloudformation create-change-set/u);
+ assert.match(script, /cloudformation describe-change-set/u);
+ assert.match(script, /cloudformation execute-change-set/u);
+ assert.doesNotMatch(script, /cloudformation deploy/u);
+ assert.match(script, /functions\/\$\{function_hash\}\.zip/u);
+ assert.match(script, /layers\/\$\{layer_hash\}\.zip/u);
+});
+
+test("the Layer builder pins source, architecture, license and the only installed surface", async () => {
+ const builder = await readFile(join(service, "build-layer.mjs"), "utf8");
+ assert.match(builder, /38f5363bef58d74547e5055846d76d8b20bb2872a87b0aab71611b010b437a6f/u);
+ assert.match(builder, /linux64-gpl-shared-8\.0\.tar\.xz/u);
+ assert.match(builder, /\["bin\/ffmpeg", "bin\/ffprobe", "lib", "LICENSE\.txt"\]/u);
+ assert.match(builder, /magic\.readUInt16LE\(18\) !== 62/u);
+ assert.match(builder, /GPL-3\.0-or-later/u);
+ assert.match(builder, /verbatimSymlinks: true/u);
+ assert.match(builder, /isAbsolute\(target\)/u);
+ assert.match(builder, /await stat\(resolved\)/u);
+});