# Use Media Core

Download, inspect, and process local media artifacts.

Media Core fits applications that own job lifecycle and storage. Prefer `WorkerRuntime` for the worker's limits, retries, collection handling, and temporary-directory lifecycle.

## Interface

| Method                                   | Responsibility                                      |
| ---------------------------------------- | --------------------------------------------------- |
| `resolveMedia(url, options)`             | Return a plan: URL, output type, and engine names   |
| `downloadMedia(url, directory, options)` | Download and validate a local artifact              |
| `inspectMedia(filePath, preferredName?)` | Describe an artifact and attempt media probing      |
| `processMedia(artifact, options)`        | Extract, convert, or fit media according to options |

`resolveMedia()` plans work. It does not probe source availability. Engine names are execution details; do not make their current order part of your public client contract.

## Single-file example

Run from the built worker repository root. Replace the URL with a direct media file you may download.

```javascript
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { createMediaCore } from "./dist/index.js";

const directory = await fs.mkdtemp(path.join(os.tmpdir(), "media-example-"));
const core = createMediaCore();
try {
    const artifact = await core.downloadMedia(
        "https://example.com/video.mp4",
        directory,
        {
            outputType: "video",
            quality: "best",
            maxBytes: 100_000_000,
            signal: AbortSignal.timeout(120_000)
        }
    );
    const inspected = await core.inspectMedia(artifact.filePath, artifact.fileName);
    console.log({ bytes: inspected.sizeBytes, mediaInfo: inspected.mediaInfo });
    // Copy or store the file before the temporary directory is removed.
} finally {
    await fs.rm(directory, { recursive: true, force: true });
}
```

The program creates and owns the temporary directory above. Never substitute a caller-supplied directory in that cleanup operation.

## Output choices

Quality IDs are `best`, `1080p`, `720p`, `480p`, `360p`, and `audio-only`. Job input does not accept raw extractor format selectors.

Original format preserves the selected source where possible. Audio extraction can copy a compatible stream without re-encoding. MP3/MP4 conversion or fitting can require processing; height preferences depend on available source variants.

Use [runtime collection handling](/docs/en/worker/jobs) for albums rather than assuming one `filePath` represents an entire post.