timeline

GET /timeline

The sequences the caller may read, newest first.

Q11. The caller's own, and every studio's when it holds `gallery.read_all`. Deleted sequences are not listed.

Needs the timeline capability.

POST /timeline

Create a sequence from clips, or from whole tracks.

R44, R45, 05 §7. Either `clips`, which are laid end to end from 0 on V1 for video and images and on A1 for sound, or `tracks` — not both. Neither makes an empty sequence, which is valid to store and cannot be exported until it has a video clip. `target.sample_rate` defaults to 48000 (Q9). Every clip must name an asset the caller may read (Q11); one it may not is 422 `invalid_timeline`, worded the same whether or not the asset exists.

Needs the timeline capability.

Request body: TimelineCreate (application/json)

GET /timeline/{id}

One sequence. One the caller may not read is 404.

Needs the timeline capability.

PATCH /timeline/{id}

Edit a sequence. Every edit is a revision.

05 §6, Q10. A JSON merge patch over `name`, `target` and `tracks`; `target` members merge, and `tracks` replaces. `If-Match` is required, and a stale one is 409 `etag_mismatch`. The document the patch produces is validated and snapped as a whole, and the document it replaces is kept as the previous revision. A clip this write adds must name an asset the caller may read; one already in the sequence may stay (Q11).

Needs the timeline capability.

Request body: TimelineUpdate (application/merge-patch+json)

DELETE /timeline/{id}

Delete a sequence. Its exports and their lineage stay.

Q12. A soft delete: the row stays, so an exported item keeps naming it, and its clips stop holding their footage against reclaim. There is no restore. `If-Match` is checked when sent.

Needs the timeline capability.

GET /timeline/{id}/exports

The sequence's export jobs, newest first.

Q17. Under `timeline`, so a studio that exports need not also hold `jobs` to watch what it started. The same jobs appear in `/jobs` for a studio that does hold it.

Needs the timeline capability.

POST /timeline/{id}/exports/{job}:cancel

Stop a running export and leave nothing behind.

Q16, Q17. The ffmpeg leading the export's process group is stopped and its partial file removed; the job ends `cancelled`. A finished job is 409 `job_finished`. The launcher's `POST /launcher/jobs/{id}:cancel` reaches the same runner.

Needs the timeline capability.

GET /timeline/{id}/revisions

The sequence's earlier revisions, newest first.

Q10. Each write stores the document it replaced; the newest 100 are kept. Undo is `:revert`.

Needs the timeline capability.

POST /timeline/{id}:export

Export the sequence. Answers with the job that renders it.

R46, R48, Q16, Q17. Export is a Job, so progress, cancellation and the log are the ones that already exist. The output is written where nothing looks for it and becomes an asset only after ffmpeg exits 0 and the file is probed against the target; then it is adopted, and recorded as a gallery item carrying `timeline_id` with one `clip` input per distinct asset. A sequence with no video clip is 422 `invalid_timeline`. A clip the caller may no longer read is 422. One export at a time per sequence: another is 409 `already_exporting`. Needs ffmpeg (501 `unsupported`).

Needs the timeline capability.

Request body: ExportRequest (application/json)

POST /timeline/{id}:open

Ask the framework to show its editor on this sequence.

R45, 05 §5a, §7, Q19. The data operation always works and only the presentation degrades: until the launcher has a Timeline screen, which waits for M9's cookie (Q20), this answers 501 `unsupported` with a reason, and a studio hides its button. From then it publishes the sequence to a connected launcher page and answers `{opened, surface}`, or 501 when no page is connected.

Needs the timeline capability.

GET /timeline/{id}:plan

Which path an export would take, and why.

R47, Q13. Every video clip is probed, and the answer is `copy` when every one of them matches the target and each other — codec, profile, level, size, aspect ratio, field order, pixel format, time base, frame rate, colour tags and parameter sets — and is used whole, with no hold, image or transition. Otherwise `conform`, with a reason per clip. The picture is copied; sound always goes through the conform graph, because a copied AAC stream carries its own priming and padding into every cut. So the chip reads "video stream copy", not "no re-encode". Needs ffmpeg: without it, 501 `unsupported` with `details.tool`.

Needs the timeline capability.

POST /timeline/{id}:revert

Write an earlier revision back as the newest one.

Q10. Undo is the previous revision, written forward rather than rewound, so nothing is lost. A revision naming an asset that has since been reclaimed, or one the caller may not read, is refused with the clips named (422 `invalid_timeline`). `If-Match` is required.

Needs the timeline capability.

Request body: TimelineRevert (application/json)

POST /timeline:append

Add one asset to the end of a track, without stealing focus.

R45, Q19. With `timeline_id`, that sequence; without one, the most recently updated sequence the caller owns, and 409 `no_timeline` when it owns none. `track` names a track by kind and position — `V1`, `A1`, `A2` — and defaults to `V1` for a video or image asset and `A1` for sound. It applies to whatever the current revision is, so it needs no `If-Match`.

Needs the timeline capability.

Request body: TimelineAppend (application/json)