AWS Elemental MediaConvert

Local emulators. Real API contracts. Part of Mockingbird.

Stateful AWS Elemental MediaConvert emulator for the official SDK v3 client. It supports endpoint discovery, asynchronous jobs, deterministic controls, EventBridge-compatible events, and output writes to a configured emulator S3 service.

#Install

npm install -D @crvouga/mockingbird-service-mediaconvert

ESM only. Node 22+ or Bun 1.2+.

#Usage

import {
  CreateJobCommand,
  DescribeEndpointsCommand,
  MediaConvertClient,
} from "@aws-sdk/client-mediaconvert"
import { createServer } from "@crvouga/mockingbird-service-mediaconvert/server"

// Test setup: start the emulator and point the discovery client at it.
const server = await createServer()
const aws = {
  region: "us-east-1",
  credentials: { accessKeyId: "fixture", secretAccessKey: "fixture" },
}
const discovery = new MediaConvertClient({ ...aws, endpoint: server.url })

// Application code, unchanged. DescribeEndpoints returns the emulator URL, which the
// second client uses to submit jobs.
const { Endpoints } = await discovery.send(new DescribeEndpointsCommand({}))
const mediaConvert = new MediaConvertClient({ ...aws, endpoint: Endpoints?.[0]?.Url })
const { Job } = await mediaConvert.send(
  new CreateJobCommand({
    Role: "arn:aws:iam::000000000000:role/MediaConvert",
    Settings: {
      Inputs: [{ FileInput: "s3://inputs/source.mp4" }],
      OutputGroups: [
        {
          OutputGroupSettings: {
            Type: "FILE_GROUP_SETTINGS",
            FileGroupSettings: { Destination: "s3://outputs/video/" },
          },
        },
      ],
    },
  }),
)
// Job.Status === "SUBMITTED"

await server.close()

Supported operations are DescribeEndpoints, CreateJob, GetJob, and CancelJob. CreateJob retains Role, Queue, UserMetadata, and the complete nested Settings structure. A repeated ClientRequestToken returns the original job.

#Controls

• GET /__admin/jobs and GET /__admin/jobs/:id inspect submitted jobs and exact settings.
• POST /__admin/jobs/:id/transition accepts status (PROGRESSING, COMPLETE, ERROR, or CANCELED) plus optional progress, durationInMs, size, names, errorCode, and errorMessage.
• Completing a job writes deterministic output bytes to each HLS or file-group S3 destination when s3.endpoint is configured.
• Every state change emits an EventBridge-compatible MediaConvert Job State Change event through the shared webhook hub.
• Fault presets are too_many_requests, internal_error, and unavailable.

The shared runtime provides reset, clock, journal, metrics, faults, and namespace isolation.

#API

• MediaConvertAPI, MediaConvertAPIOptions, MediaConvertEvent, TransitionOptions: handler, events, and deterministic controls.
• MediaConvertJob, MediaConvertJobStatus, OutputGroupDetail: durable job state.
• createRuntime, MediaConvertRuntime, MediaConvertRuntimeOptions: full Mockingbird runtime and webhook hub.
• MEDIACONVERT_NAMESPACE, MEDIACONVERT_PRESETS, accessKeyCredential: constants and fault controls.
• document, operationIds, supportedOperationIds: generated OpenAPI metadata.
• createServer, MediaConvertServerOptions, DEFAULT_PORT, serveTarget from ./server: Node HTTP adapter and CLI integration.

#Deliberately not modelled

Real transcoding, IAM evaluation, arbitrary operations, production limits, billing, dashboards, and codecs outside the submitted HLS/MP4 structure are not modelled.

Official oracle: AWS Elemental MediaConvert API Reference.