Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 30 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ The **strip** holds:
and cuts at once to the scene marked safe, if one is. Other remote feeds and
media stay on. Mark one from its pad's menu, BUILD's inspector with no layer
selected, or the scene graph. The scissors beside it save a replay clip (see
[Replay](#replay)).
[Replay](#replay)), and the flag drops a marker (see [Markers](#markers)).
- A row for each sound the stream carries, with its meter and mute, and the
**STREAM** meter of the audio scene on program, with **Listen** (the
headphones) to hear it (see [Audio scenes](#audio-scenes)).
Expand All @@ -227,7 +227,7 @@ The **strip** holds:
| LIVE | Watch the program while on air, and TAKE or AUTO a cued scene. |
| BUILD | Edit the scene on program, or the one open off air, shown in the middle, with its layers and what can be added on the left and the inspector on the right (see [BUILD](#build)). |
| MIX | Ride each sound's fader and mute it, open its strip for its pan and delay, and send each sound and audio scene into audio scenes, from dots under the strips or as a matrix under **Routes**. Add, rename, reorder, and remove audio scenes, put one on the stream, and listen to one on the output you pick (see [Audio scenes](#audio-scenes)). The program shows small in the strip's place for the sound. |
| REVIEW | Pick a stretch of the last 30 seconds of the program or a source from a strip of its pictures, and replay it in a replay source, slowed down if you like, or save it as a clip (see [Replay](#replay)). Beside it, this show's recordings and clips as cards with their length and size, one repaired after a crash marked so, and **Open the folder**. The program's card is the live picture. |
| REVIEW | Pick a stretch of the last 30 seconds of the program or a source from a strip of its pictures, and replay it in a replay source, slowed down if you like, or save it as a clip (see [Replay](#replay)). Beside it, this session's markers, with a clip around each (see [Markers](#markers)), over this show's recordings and clips as cards with their length and size, one repaired after a crash marked so, and **Open the folder**. The program's card is the live picture. |

The layout follows the program's shape and the window's size, giving the
picture the most room it can. A landscape program sits above the strip; a
Expand Down Expand Up @@ -475,7 +475,7 @@ setting costs. Escape or a click outside closes it.
| Show | Pick the format, landscape or portrait, which swaps the canvas's sides; **Both at once**, which sends a portrait picture beside a landscape one (see [Both formats at once](#both-formats-at-once)); the canvas size as 720p, 1080p, 1440p, or 4K, with the upload each wants, for both pictures while Both at once is on, or **Custom** for exact numbers; the frame rate as 30, 60, or **Custom**; and, under **Scene sizes**, each scene's own size (see [Published scenes](#published-scenes)). Saved in the scene file, and undone like any edit. |
| Stream | Set the relay, its token, the failover relay, the broadcast's name, and on demand (see [Stream settings](#stream-settings)). |
| Recording | Change or open the recordings folder, and pick the picture and the audio scene a recording holds, and whether each source records a file of its own too (see [Recording](#recording)). |
| Hotkeys | Bind keys, by what they are for: going live, ending the stream, the panic key, and recording; Studio mode, TAKE, and AUTO; each scene; each sound's mute; and replay and clips (see [Hotkeys](#hotkeys)). |
| Hotkeys | Bind keys, by what they are for: going live, ending the stream, the panic key, and recording; Studio mode, TAKE, and AUTO; each scene; each sound's mute; and replay, clips, and markers (see [Hotkeys](#hotkeys)). |
| Guests | Set the room guests join, its key, the join page, how long a link lasts, and whether guests appear on their own (see [Guests](#guests)). |
| Advanced | Publish scenes as broadcasts of their own and sources independently, turn the virtual camera of the program or of each published scene on, pick how the window's [effects](#effects) move, and open the [scene graph](#scene-graph). |

Expand Down Expand Up @@ -1718,12 +1718,12 @@ Quitting first lets the recording's encoders publish what they still hold, and
the program's file keeps it. A file nothing reached before the recording
stopped is removed.

While a file is written, a marker `<name>.mp4.unfinished` sits beside it. A
crash, a power loss, or a write that failed leaves the marker, and the next
While a file is written, a sidecar `<name>.mp4.unfinished` sits beside it. A
crash, a power loss, or a write that failed leaves the sidecar, and the next
launch repairs that file without asking: it writes `<name>.repaired.mp4`
beside it, numbered if a file already has that name, a regular MP4 of
everything the file holds up to its last complete fragment, leaves the
original untouched, and removes the marker, so the file is repaired
original untouched, and removes the sidecar, so the file is repaired
only once. The repair runs in the background and appears at the top of the
Health window and in the log, and REVIEW marks its card **Repaired after a crash**. A file another studio is still recording into the
same directory is left alone.
Expand All @@ -1748,7 +1748,7 @@ a WebGL page runs slower.

Settings, Hotkeys binds a key to the **Panic** key, TAKE and AUTO
for the cued scene, turning [Studio mode](#off-air-and-studio-mode) on or off,
**Replay**, **Save clip**, starting or stopping a recording, **Go live**,
**Replay**, **Save clip**, **Drop a marker**, starting or stopping a recording, **Go live**,
**End stream**, each scene, which its key takes, or cues in Studio mode,
as its pad does (the tab says which), and each sound, which its key mutes or
unmutes, as its strip's button does. The [command palette](#command-palette)
Expand Down Expand Up @@ -1862,6 +1862,29 @@ no past to replay: a page publishes no track of its own, so replay the program
to show it. A replay source on program encodes each replay as its own track
while it plays, like a camera.

## Markers

Drop a marker on a moment as the show runs, on air or off, with the flag
beside the panic key or a key bound to **Drop a marker** (see
[Hotkeys](#hotkeys)). REVIEW lists this session's markers, the newest first,
each numbered in the order dropped, with how long ago it was. Type a name in
its row, or remove it. Each marker still within the last 30 seconds shows on
the strip as a numbered flag.

The scissors in a marker's row save a clip around it, as **Save clip** does,
of what REVIEW has picked to replay: from 10 seconds before the marker to 5
after, or up to now while those 5 have yet to pass. The same keyframe limits
apply. A clip reaches back only 30 seconds, so a marker older than that has
no clip; its scissors say so.

The markers are kept beside the recordings, not in the scene file:
`show 2026-11-18T12-00-00Z.markers.toml` for `show.toml`, named for when the
studio opened the show, lists each marker's number, the UTC moment it was
dropped, and its name. It is written again on every change and removed once
no marker is left, in the background, so a slow disk never holds up a key. A
marker the folder refuses is kept for the session anyway, and REVIEW says why
until a write succeeds. A session holds at most 255 markers.

## A capture gone dark

A camera, display, or window can go black while its capture still runs: a
Expand Down
37 changes: 26 additions & 11 deletions quest/m2/markers.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,34 @@
# [M] Markers and clips
# [S] Recordings carry markers as chapters

## Goal

A key or a button drops a marker on the show as it runs. The REVIEW page
shows markers on its strip and in a list, a clip is cut around one in a
click, and a recording carries its markers as chapters.
A recording carries the session's markers that fall inside it as chapters,
each titled by the marker's name or number, which a player such as mpv or
VLC lists and seeks to.

## Plan

Planned 2026-11-09 (maintainer, /quest-plan), and held for later: ✅ m2
(rejected: m1).
(rejected: m1). Markers, their list and strip on REVIEW, and a clip around
one shipped in [moq-dev/studio#209](https://github.com/moq-dev/studio/pull/209);
the chapters wait on moq-mux, since the studio cannot place a moment in a
finished file: where the movie starts on the program clock is known only
inside moq-mux's export, and on moq's `main` its `Finish` is opaque.

- A marker is a time on the program clock and an optional name. Markers of
a session are kept beside the recordings, not in the scene file.
- A clip around a marker uses Save clip's copy without re-encoding, so the
same keyframe limits apply.
- Chapters are written when a recording becomes a regular MP4.
- Marker is a hotkey action.
- Chapters are written when a recording becomes a regular MP4: as it stops
or the studio quits (`finish` in `rs/moq-studio/src/record.rs`), and as a
launch repairs one a crash left (`rs/moq-studio/src/record/repair.rs`).
- A marker's moment is its `at` (`rs/moq-studio/src/markers.rs`) on the
program clock (`Program::clock`'s `capture` in `engine.rs`), which every
recording shares; moq-mux places it in the movie.
- Recommended: each marker's program-clock reading goes in the session's
markers file, and each recording's `.unfinished` sidecar names that file,
so a repair at the next launch finds the markers of the session that
recorded it. The recorder's own `Marker` type, that sidecar, becomes
`Sidecar` then, since the two meet in `record.rs`.
- Recommended: a chapter starts at each marker, with none before the first,
since a marker is a moment, not a span.

## Required

- [moq-mux's MP4 chapters pinned](/quest/m2/pin-mp4-chapters.md) - brings moq-mux's chapters on a finished MP4 into the `moq` submodule
31 changes: 31 additions & 0 deletions quest/m2/pin-mp4-chapters.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# [XS] moq-mux's MP4 chapters are pinned

## Goal

The `moq` submodule includes a way to give a recording that moq-mux's
`container::mp4` finishes, by `Export::finish` or `repair`, chapters: each a
moment on the recorded broadcast's timeline and a title, written into the
regular `moov`.

## Plan

moq-mux is where this belongs: it alone knows where the movie starts on the
broadcast's timeline, and on moq's `main` its `Finish` is opaque, so the
studio cannot edit the `moov` itself. mp4-atom 0.17, which moq-mux already
uses, encodes the Nero `chpl` box that ffmpeg, mpv, and VLC read.

Once the wait clears, advance it with `just upgrade-moq` in its own PR,
fixing whatever the new API breaks here.

## Required

- [The studio catches up to moq's main](/quest/m0/pin-moq-tip.md) - absorbs the tip's other breaks, so this pin moves only by chapters

## Waiting

- moq-dev/moq: moq-mux's regular MP4 finish takes chapters. The change has
no quest in moq's tree yet; it was found by
[moq-dev/studio#209](https://github.com/moq-dev/studio/pull/209) and is
listed in its Follow-ups for `/quest-plan` there. Check:
`rs/moq-mux/src/container/mp4.rs` on moq's `main` writes chapters into the
finished `moov`.
30 changes: 30 additions & 0 deletions quest/m2/try-markers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# [XS] Try markers

## Goal

The maintainer tries markers on their own machine and either signs them off
or files what they find as quests.

## Plan

Markers are on `main` (`cargo run -p moq-studio --features capture`). What
to try, on a show going live to a relay:

- **Feel:** dropping a marker with the flag beside the panic key and with a
bound key while a game has focus, then naming it, clipping around it, and
removing it on REVIEW.
- **Look:** the numbered flags on REVIEW's strip and the list over the
recordings, at a normal window size.
- **Fit:** whether 10 seconds before a marker and 5 after is the clip you
want, and whether a marker older than 30 seconds should clip at all before
[clips from a recording](/quest/m3/marker-clips.md) land.

An agent then turns each finding into a quest, or an edit to the quest that
owns that part, and deletes this one.

## Waiting

- Maintainer: try markers as the Plan lists and report what to change, or
that nothing needs to. An agent cannot judge feel or taste; a kittest run
and `just shots` already cover the clicks and the layout. Check: a comment
or quest records the result.
23 changes: 23 additions & 0 deletions quest/m3/marker-clips.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# [M] A clip around an older marker, from the recording

## Goal

A marker older than the last 30 seconds still gets a clip around it, in one
click on REVIEW, cut from the recording that holds it without re-encoding,
as a clip from the recent past is. A marker no recording holds says so.

## Plan

A clip from the recent past copies the program's track, which keeps only 30
seconds (`rs/moq-studio/src/replay.rs`), so today a marker past that has no
clip. A recording holds the rest: import it through moq-mux, from the
keyframe before the marker's span, and export the span as Save clip does, so
the same keyframe limits apply. A finished recording is a regular MP4, which
moq-mux's regular MP4 import reads; one still being written is a fragmented
MP4, which its fMP4 import already reads.

Here in m3 because the import it needs is pinned in m3.

## Required

- [MP4 import pinned](/quest/m3/pin-mp4-import.md) - brings moq-mux's regular MP4 import into the `moq` submodule
14 changes: 14 additions & 0 deletions rs/moq-studio/assets/icons/flag.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading