> Canonical guide: https://developers.foxlight.ai/build/tutorials/video-studio/assets/
> Contract snapshots: Skulk 2.0.0 (b0af39c79b6b7102b2478062904f1d7cc8619975); SDK 0.4.0 (31bb090b8f64689f87514e48385e22b6ad94a6c2). Check the installed runtime when versions differ.

# 7. Own assets and saved takes

A media application needs more than a job table. Studio owns imported references, completed clips, thumbnails, rewritten prompts and retention marks. These files live under the host-provided durable state directory.

The SDK provides protected directories and atomic-write helpers. Studio implements media identity, validation and retention. Do not confuse a persistence helper with a complete media library.

## Import bytes, then give them an identity

`AssetLibrary` addresses assets by SHA-256. A reference identifies a digest and role rather than an arbitrary engine-local path. Labels are editable metadata; they do not change the bytes' identity.

The import path:

1. Admit a bounded source or upload.
2. Stream it into a temporary file while measuring and hashing.
3. Determine media type from content, not only the filename.
4. Validate media metadata and supported dimensions.
5. Publish into the application library atomically.
6. Return metadata small enough for a capability reply.

Studio rejects unsafe file types, symlinks and sources that change during import. Files must be owner-controlled regular files. The per-asset bound is 128 MiB; the library also has an aggregate byte bound and entry limits. Multiple render references share a bounded aggregate snapshot allowance.

A local import path is interpreted by the application on its own host. It is not a path on a remote caller's computer. Browser upload is the portable way to send a file from the operator's machine.

## Upload without embedding media in JSON

The scoped application route `PUT api/assets/upload` accepts a raw, bounded request body with a declared content length. The client sends file bytes directly. JSON is used for the resulting digest, dimensions, label and other metadata.

For generation, `_snapshot_asset` reopens and verifies each referenced file before passing bytes to Skulk. This closes the gap between reviewing an asset's metadata and using its current content. Moving an asset's file after planning must not make the engine ingest different bytes under the old digest.

Keep media out of operation results and control messages. A digest and metadata travel well; a base64 movie does not.

## Separate completion from retention

Once collected, a clip is application-owned. Its job id links it to the render record, but keeping a take is a Studio action.

| Action | Meaning                                                     |
| ------ | ----------------------------------------------------------- |
| Keep   | Protect the saved take from ordinary pruning.               |
| Forget | Remove that protection; do not immediately delete the clip. |
| Delete | Remove the local clip/thumbnail and record the deletion.    |

The default `keep_renders` setting retains 32 unkept renders. Kept takes remain protected. Journal retention and file retention are separate policies: retaining an operation record does not guarantee that its local clip still exists.

Deleting a saved take does not implicitly delete a model, terminate an inference instance or erase unrelated Skulk job state. Those resources have different owners.

## Make recovery part of storage design

Studio waits for earlier cleanup before publishing collected output to avoid deletion races. It cleans incomplete temporary files and keeps thumbnail backfill separate from successful clip collection. History migration preserves scope and replay fences; it must not overwrite newer records.

For a beginner implementation, start with one durable root, digest-addressed imports and an explicit retention policy. Add labels and thumbnails after the ownership rules are clear. Test corrupt files, interrupted writes, changed sources and cleanup racing with completion.

Next: [browser interface](https://developers.foxlight.ai/build/tutorials/video-studio/application/).