# kixel.live Studio `moq-studio` is a native streaming studio for Linux, macOS, and Windows. It composes cameras, screens, windows, images, colors, web pages, HTML and CSS overlays, and broadcasts from a relay into scenes on the GPU, mixes their audio, and publishes the result to a [MoQ](https://github.com/moq-dev/moq) relay. It is early. On Linux, each [release](https://github.com/moq-dev/studio/releases) ships a Flatpak bundle for x86_64 and aarch64: ```bash flatpak install --user moq-studio-x86_64.flatpak flatpak run live.kixel.studio ``` Its menu entry opens [your shows](#your-shows) and saves recordings to your Videos folder. The sandbox reaches cameras through the camera portal, which asks once, and files under your home directory. The virtual camera is its PipeWire node only, since the sandbox has no `/dev/video*`. On macOS 13 or later, each release ships the app for Apple silicon (`moq-studio-macos-arm64.dmg`) and Intel (`moq-studio-macos-x86_64.dmg`), signed and notarized. Open the disk image and drag **kixel.live Studio** to Applications. Opened from Finder or the Dock, it opens [your shows](#your-shows). macOS asks you to grant it the camera, microphone, and Screen & System Audio Recording permissions, the last in System Settings > Privacy & Security. Run it from a terminal with the flags below as `"/Applications/kixel.live Studio.app/Contents/MacOS/moq-studio"`. Elsewhere, build it from source. The moq crates come from the `moq` submodule: ```bash git clone --recurse-submodules https://github.com/moq-dev/studio cd studio cargo run --release -p moq-studio --features capture,openh264 ``` - With no arguments, the window opens on [your shows](#your-shows). Name a show to open it at once: `moq-studio show.toml`. A show is its scene file; if it does not exist yet, [guided setup](#first-launch) proposes one and creates it. Changes are saved to it a second after you stop editing, with no save step. - Nothing is published until you [go live](#going-live) from the window, and you end the stream from it too. Until then the studio composes, previews, and records, and broadcast sources and guests play through the show's relays. - Where a show streams is in Settings, Stream (see [Stream settings](#stream-settings)), kept beside the show. A flag sets one for a single run, over the show's own, and is never saved: `--connect` (the relay) with `--connect-token`, `--failover`, `--broadcast`, `--on-demand`, `--recordings `, where recordings and clips go (by default beside the show), and the guest flags. - A failover relay publishes the same broadcast to a second relay under the same broadcast instance, so a viewer linked to both resumes mid-group from it when the first fails. Both relays must speak the one `--connect-version`, which must carry instances (`moq-lite-07-wip` today, which a relay accepts only when configured to), or going live with both refuses; it also refuses a fixed `--connect-bind` port, since each relay's connection binds its own. Each relay's token is its own: `--connect-token` goes to the `--connect` relay only. The stream's tracks claim their bitrate on the first relay's link alone, so only that link is probed toward the stream's rate, and the video follows that link's estimate alone. - Quitting while live ends the stream as **END STREAM** does: every track ends after its last pictures and sound, then each relay session closes once the relay has them, waiting up to about a second, so viewers and recordings on the relay see the broadcast end rather than cut off. - `capture` adds camera, display, window, microphone, and system-audio sources, and listening to an audio scene. On Linux it links ALSA; add `pipewire` for PipeWire cameras and the [virtual camera](#virtual-camera)'s PipeWire node. `openh264` is the software H.264 fallback for a machine without a hardware encoder. - `release` is what the packages build: `capture`, `openh264`, and the hardware codecs. The Flatpak adds `pipewire`. - `cef` adds browser sources, on Linux only for now. The build takes CEF from `CEF_PATH`, which the dev shell sets, or else downloads it, and the binary loads `libcef.so` from beside itself or from that `CEF_PATH`. - On Linux, display and window sources capture X11 and XWayland by id. With `pipewire`, a display or window can also be picked in the desktop's screen-sharing picker, the only way to share a Wayland screen; see [Picked displays and windows](#picked-displays-and-windows). - On macOS, a build from source is not an app bundle, so the camera, microphone, and Screen & System Audio Recording permissions are asked of, and granted to, the app that launched it, such as your terminal. Display, window, and system-audio sources need the last, granted in System Settings > Privacy & Security. - The `--connect-*`, `--quic-*`, and `--log-level` flags are [moq-cli's](https://doc.moq.dev/bin/cli); see `moq-studio --help`. - `moq-studio --watch ` opens no scene file and plays a studio broadcast instead, as a viewer sees it; see [Watching](#watching). ## Your shows Opened with no show, or after **Close show**, the window lists the shows you have opened, the latest first, each with the last picture of its program, its shape, and when it was last live and for how long. Click one to pick up where it ended; nothing goes live until you say so. **New show** asks where to keep a new show's file and starts [guided setup](#first-launch) there, and **Open a show file** opens any other. Right-click a show to forget it; one whose file has moved says so. The list and the pictures are yours, kept with the app's settings rather than beside any show, and a show's picture is saved as the window closes or the show does. ## First launch Opening a show whose scene file does not exist yet starts guided setup instead of the studio. It runs three checks, and a check that fails shows its reason: - **Devices:** the cameras, displays, and audio inputs this machine has. - **Encoders:** for each canvas setup can propose (1080p and 720p at 60 or 30 fps, and 360p at 30 fps), the encoder the program would pick, whether it reads the GPU, the bitrate it encodes at, and how long a frame takes over a short burst of moving frames. An encoder keeps up when a frame takes at most three quarters of the frame period, leaving the rest for sources and the compositor. - **Uplink:** with a relay, from `--connect` or the show's stream settings, setup publishes a probe at the broadcast's path for about six seconds and subscribes to it through the relay, so the relay pulls it. The congestion controller's send-rate estimate is the measurement. With a failover relay, only the first is measured, since only its link is probed toward the stream's rate. A connection that reports no estimate, such as WebSocket, fails the check. Setup then proposes a scene named Main and a canvas, explaining each choice. The scene has the first display filling the canvas, the first camera in the bottom-right corner over it (or filling the canvas alone), and the first audio input. Swap any of them for another device or leave it out. The canvas is the largest one whose encoder keeps up and whose video and audio fit in two thirds of the measured uplink, the most the [Health](#health) window grades healthy. Without a measurement, it is the default 1080p at 30 fps. If no encoder keeps up, it is the canvas closest to keeping up. Nothing is written until you start the studio, so quitting during setup runs it again on the next launch. **Start with this scene** and **Start with an empty scene** both create the scene file at once, the second with the chosen canvas and no sources. The proposed scene is the first edit in the history, so undoing it leaves that empty scene. Setup writes an ordinary scene file. Change its sources and scenes on the BUILD page, its canvas in Settings, and where it streams in Settings, Stream. The health dot shows how the uplink holds up once you are live. Your shows and setup sit in the desktop's own window frame, and the studio then draws its own (see [The window](#the-window)); closing the show brings the desktop's back. On macOS the system's title bar stays until the next launch. ## The window The studio opens to its **LIVE** page: the program as large as the window allows, in a neutral frame tagged **OFF AIR** until you go live, then a blue one tagged **ON AIR**. The title bar and the strip along the bottom stay on every page, so the scenes, the sound, and the panic key never leave the window while you are on air. Blue, the studio's accent, means on air (and marks what is picked or switched on), amber anything cued, off air, muted, or degraded, and red an error, such as a failure or a clipping meter. An icon-only button names itself, and its key, under the pointer. The **title bar** is the window's own: drag it to move the window, double-click it to maximize, and drag the window's edges to resize it. On macOS the system's buttons and edges stay. It holds, from the left: - The show's name. Its menu has the scene file's path, **Reload the scene file**, **Copy the selected layer**, **Paste**, **Open the multiview** (see [Multiview](#multiview)), and **Close show**, which ends the show as quitting does (saving it, finishing a recording, and letting go of its relays, sources, and keys) and returns the window to [your shows](#your-shows). It is dimmed while the stream is on air or going on or off: end the stream first. A close that cannot save the show, because the scene file changed outside the studio, stays open and says so. - Undo and redo, each naming under the pointer the edit it would step, and the history (the clock), which lists every edit, newest first: pick one to undo or redo back to just after it. - The pages: **LIVE**, **BUILD**, **MIX**, and **REVIEW**. - The health dot, the stream's worst grade at a glance. Click it for the worst problem first, then each destination, who is watching, and the encoder, and **Details** for the [Health](#health) window. Off air it reads **Ready** once the show has a relay, and **No relay** until then. While a capture a live scene shows has [gone dark](#a-capture-gone-dark), or a camera or broadcast it shows [stopped sending pictures](#a-picture-that-stalls), and those are among the worst problems, it counts them, as **1 layer dark**, **1 layer stalled**, or **2 layers dark or stalled**. - Record, which starts or stops a [recording](#recording) from any page, with the picks in Settings, Recording. Its dot pulses while recording, with how long it has been recording beside it. - The live control: **GO LIVE** off air, which opens the [go-live sheet](#going-live); on air, **LIVE** and how long the stream has run, which reads **END STREAM** under the pointer. - Search, which opens the [command palette](#command-palette). - The gear, which opens [Settings](#settings). - Minimize, maximize, and close, except on macOS. The **strip** holds: - A **pad** for each scene, its picture redrawn a few times a second, with its name, its hotkey, an ON AIR tag on the scene on program (before going live, a **FIRST** tag in amber, as the stream opens on it), and a NEXT tag on the scene cued or open off air. Click a pad to take its scene on air by the show's transition (see [Transitions](#transitions)), or to cue it in [Studio mode](#off-air-and-studio-mode); clicking the scene already on air leaves nothing cued. A scene that cannot go on air, of another size or showing the program, has a dimmed pad that says why under the pointer. Right-click a pad to take its scene, cue it in Studio mode, **Edit off air**, mark it the safe scene, rename it, duplicate it, move it left or right, or remove it. **Duplicate** adds a scene after it showing the same sources, linked, so an edit to a source's look shows in both; **Duplicate with its own copies** gives each of its layers a copy of its source to edit apart (a scene or the program drawn in it stays one picture). A pad ringed in red says what just failed on it under the pointer. The last pad, **+**, adds an empty scene without taking it, and the switch after it turns [Studio mode](#off-air-and-studio-mode) on and off. - The **panic key**, amber and named for the safe scene: it mutes every microphone and every guest (their camera's sound and their screen's), hides every always-on-top layer, whatever it shows, in one edit undo takes back, 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)). - 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)). | Page | Use it to | | --- | --- | | 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. | 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 portrait one moves the pages to a sidebar on the left and the scenes and sound to columns beside the picture; and a narrow window stacks the scenes, the panic key, and the sound under the picture. The window is at least 640x600. A message about what the last action did shows over the bottom of the page for a few seconds, an error a little longer. A conflict with an outside edit to the scene file, or a failed save, shows over its top until it is settled. An error with a place shows there instead: on the layer's row and in the inspector, on a scene's pad, or in Add, for ten seconds or until the next edit there succeeds. ### BUILD BUILD edits the scene on air as viewers see it: every change is live at once, unless a scene is open [off air](#off-air-and-studio-mode). What a scene draws is a stack of **layers**, each placing one source. **Layers**, on the left, lists them front first in two groups: **Always on top**, drawn over every scene on program and staying on through a cut or transition (a downstream keyer for a logo or a lower third), and **This scene**, the edited scene's own: the one on program, or the one open off air. Each row has an icon for the source's kind, its name, what it shows (and **linked ×3** when three layers show the source), and its eye, which shows or hides it. A lock shows on a locked row, and on the selected or pointed-at one to lock it. A dot says a source is not live, such as starting, stalled, offline, ended, or failed, with the words on hover, and an error on the layer replaces what it shows, in red. A capture [gone dark](#a-capture-gone-dark), or a camera or broadcast whose picture [stalled](#a-picture-that-stalls), has an amber badge instead, which opens what happened and the fix. Click a row to select its layer, drag it up or down its group to restack it, and right-click it for its menu: hide or show, lock or unlock, interact with a web page, bring it to the front or forward or send it backward or to the back, keep it always on top or move it into this scene, duplicate it (linked, or as its own copy), make it independent, copy it, or remove it. **Add a layer** (A) turns to Add. **Add** lists what can be placed: what a drop or paste makes (see [Dropping and pasting](#dropping-and-pasting)), the kind a drag over the window holds lit; the sources no layer shows, no audio scene hears, and nothing reads, each with **Add**, to place it in the edited scene, or the bin, to remove it for good; this machine's cameras, displays, windows, and audio inputs; any source by hand; and, with a room, guests: invite one, show their join link as a QR code in a sheet over the window, see who joined, and take a guest out of every scene. A new source with a picture is placed in front of the edited scene, and selected. On the **picture**, click a layer to select it, drag it to move it, and drag its edges or corners to resize it (see [Placing layers](#placing-layers)). A locked layer stays put: clicks pass through it to what is under it. A small toolbar beside the selected layer offers **Crop**, after which dragging an edge trims the picture without scaling it and dragging inside moves the picture under the frame, with the whole picture outlined; **Fit**, as large as fits on the canvas, keeping its shape; **Fill**, covering the canvas, keeping its shape and cropping the rest evenly; **Shape**, square, rounded, circle, or arch; **Cut out**, removing the background of a source that can lose it; **Interact**, on a web page; and **...**, the row's menu. Right-click a layer for the same menu, or the picture elsewhere to add a layer, paste, or set **Snap**, **Grid**, and the grid's spacing. Escape ends cropping, then the selection. A layer in a [slot](#slots-and-roles) is outlined on the picture, dashed, with a chip naming its role, or **Guest** or its slot, and a tag naming the source it shows. It has no handles, nor Fit and Fill, since its slot places it: drag it onto another slot, or drag a row of Layers onto a slot, to swap the two layers' places. A row in a slot says **Main slot** or **Tile** before what it shows. The row's menu puts a layer in the main slot or a tile, or sets it free where it is drawn. **Interact** passes the mouse and keyboard to the selected layer's web page alone, even where another layer is over it, while the picture says so; Escape or **Stop** ends it. The **inspector**, on the right, follows the selection. For a layer, its tab is named for it, with these sections: | Section | Use it to | | --- | --- | | Place | Pick its [slot](#slots-and-roles), or none; type or drag its position and size, and its crop, in percent off each edge, fit or fill it, lock it, and switch on **Keep out of the way** (see [Keeping out of the way](#keeping-out-of-the-way)). A layer in a slot has no position or size of its own to type, and keeps out of the way only when set free. | | Shape | Pick its outline, square, rounded, circle, or arch, give it a border inside that outline and the border's color, and give it a soft shadow, which follows the outline and is the layer's first drop shadow filter. | | Look | Remove its source's background, which every layer showing the source loses (make it independent to cut out here alone); grade its color through a LUT source; add, order, set, and remove its filters, copy them, or paste copied filters after its own; and set its blend mode. | | Shown in | See how many places show its source, **Linked in 3 scenes**, and **Make independent**, which points this layer at a copy of the source of its own, keeping its look, so editing that look no longer edits the others. A copy says what it copies. | | Source | See what the source is and whether it and its own track are live. A camera or broadcast without a new picture, or a microphone or system audio without new sound, for a second reads as stalled; a broadcast says how far behind it plays, and a web page whether it is copied on the GPU or, as a fallback, uploaded from memory, saying why. A media file reads as ended once it plays to its end without looping: **Play** plays it from its start, **Stop** stops it at once, blank and silent, until played again, and **Reload** reads the file again; **Reload** restarts a web page, and opens a picked display or window again, as after the picker was cancelled or sharing stopped. Publish it independently (see [Published independently](#published-independently)), and set its own crop and filters, before the layer's, on every layer showing it. **Warn when it goes dark**, on by default for a camera, display, or window, watches it for [going dark](#a-capture-gone-dark). For a role, pick the source filling it. | Its **Animate** tab holds the layer's keyframes (see [Keyframes](#keyframes)). With no layer selected, the inspector shows the edited scene: rename it, see its size, mark it **Safe**, switch on **Publish** and pick the audio scene it carries (see [Published scenes](#published-scenes)), arrange its slots and fill their roles (see [Slots and roles](#slots-and-roles)), and pick the show's transition and how long it takes, or for a stinger its media source and cut point (see [Transitions](#transitions)). A scene on program, or still leaving it in a transition, cannot be removed, even by an undo, until program cuts away from it. In a narrow window, the inspector is a tab beside Layers and Add. ### Off air and Studio mode **Edit off air**, in a pad's menu, opens its scene on BUILD without taking it: the frame turns amber and reads OFF AIR, and the program shrinks to a corner beside a banner. **Take it live** puts the scene on air by the show's transition; **Back to live** goes back to editing the scene on air. Any scene opens off air, even one that cannot go on air. One viewers see anyway, still leaving program in a transition, published or recorded on its own, or shown by a scene they see through a scene source, reads NOT ON PROGRAM instead, and the banner says how they see it, since an edit reaches them. Off air, Layers lists the scene's own layers alone: the always-on-top ones are drawn on program, so editing them, or keeping a layer always on top, waits for **Back to live**. **Studio mode**, off by default, is for an operator running a show: with its switch at the end of the scene strip on, a pad or a scene's hotkey cues its scene instead of taking it. A NEXT card docks on the program, on LIVE and on BUILD, with the cued scene as it will go on air, its keyframes and overlays started over. **TAKE** puts it on air at once and **AUTO** by the show's transition; **Edit** opens it off air, from where **Back to live** leaves it cued; and the close clears the cue. On BUILD the card moves to the opposite corner while the selected layer is under it, so it hides neither the layer nor its toolbar, even mid-drag. Studio mode is kept per user, with the [hotkeys](#hotkeys), not in the scene file. ### Command palette **Ctrl+K** (**Cmd+K** on macOS), or the search button in the title bar, opens a search box over any page that runs anything the studio can do. Type a few letters of what you want, pick a row with the arrows or the pointer, and press Enter or click it; Escape, a click outside it, or Ctrl+K again closes it. It lists: - Every action a [hotkey](#hotkeys) can do, by what it is for, each with the key bound to it: going live, ending the stream, the panic key, recording, Studio mode, TAKE and AUTO, taking or cueing each scene, muting or unmuting each sound, and replay and clips. One that cannot run now stays listed, dimmed, saying why, such as TAKE with nothing cued or a scene that cannot go on program. **Go live** opens the go-live sheet, as GO LIVE does; the rest act at once, as their keys do. - Selecting each layer of the scene BUILD edits, by its source's name. - Adding a camera, screen, window, or input: the first time, **Find cameras, screens, windows, and inputs to add** lists them, then each is a row of its own, added as a layer as the Add tab adds it. **Add a source** opens the Add tab on any kind of source, to fill in by hand. - The pages, each Settings pane, and each setting by its name, such as **Frame rate** or **Room key**, which opens its pane at that setting. - Undo and redo, naming the edit, the multiview, the stream's health in detail, and the scene graph. A row is found by the words of its name, what it is for, and a few more it answers to, such as `fps` for the frame rate or `mic` for a mute, so `mute desk` finds **Mute `desk`**. ### Multiview **Open the multiview**, in the show's menu, opens a window for another monitor with every scene and the sources you pick live in one grid, as large as the window allows: the scene on air framed in blue and tagged ON AIR, the one cued (or, off air, the one the stream opens on) framed in amber, and a blue dot on each source the live picture shows. A source [gone dark](#a-capture-gone-dark) or [stalled](#a-picture-that-stalls), and each scene showing it, carries the amber badge, and the source's picture says so. Over the grid are the show's name, a clock in this computer's time zone, the stream's health, and how long it has been live. Click a scene's tile to take it, or cue it in Studio mode, as its pad does; its hotkey shows on the tile and works with the multiview in front. The multiview draws on its own, so it stays live while the studio's window is minimized or behind a game. Sources that move on their own (cameras, screens, windows, guests and other broadcasts, web pages, video files, and replays) are on it until you leave one out, from its tile's right-click menu or the eye in the corner, where you can also add a still, a color, or a copy. The tiles on air and cued are redrawn at the program's frame rate, and the rest ten times a second. **F11**, the square in the corner, or a double-click on the header goes full screen on the monitor the window is on, and **Escape** comes back. Whether it is open, where it was, whether it was full screen, and each show's picks are kept per user, with the [hotkeys](#hotkeys), not in the scene file, so it opens where you left it next time. Wayland does not let an app place its own window, so there the desktop picks where it opens. ### Going live **GO LIVE** opens a sheet that says which scene the stream opens on, then: - **Where it goes:** the show's relay and its failover relay, each with a switch and its state, such as *Connected, 18 ms away*. A relay switched off is left out of this stream. A show going out in both formats says each relay carries both broadcasts. - **Checks**, filled in as they finish: whether each camera has a picture, whether a microphone's level moves, whether the encoder keeps up with the canvas (timed as [setup](#first-launch) times it), and whether the connection to the first relay switched on carries the program (measured as setup measures it; published scenes and sources share what is left). A show going out in both formats times both encoders at once, each its own picture, so the encoder check passes when each keeps up beside the other, and needs two videos' bitrate. If a second encoder cannot open, such as a GPU encoder at its session limit, the encoder check fails and says why. A failed check is one sentence and its fix, such as **Send 720p instead**, which changes the canvas, or **Check again**. - **GO LIVE TO** the number of destinations switched on. A failed check never stops you; only having none switched on does. Going live dials each relay, failing with why if none answers within 15 seconds, then opens the program's encoders and announces its broadcast. Each time on air is a broadcast of its own. On air, the live control is the clock; under the pointer it reads **END STREAM**, and holding it down for a moment ends the stream, handing the relays its tail first, as quitting does. The **Go live** and **End stream** hotkeys do the same at once, going live to the relays switched on without the sheet. Off air, the program has no past to replay, and a replay of it says so. ### Stream settings Settings, Stream holds where the show streams, saved in `show.stream.toml` beside `show.toml` rather than in it, since a scene file is meant to be shared: - **Relay**, the one the stream goes to, and its **Token**. - **Failover relay** and its token: a second relay the same broadcast goes to, which needs one `--connect-version` with broadcast instances. - **Broadcast name**, the path on the relays, `studio` until set. - **Encode only while someone watches** (on demand), which encodes the canvas size only while someone watches (see [Output](#output)). Tokens are kept in the system's credential store (the Secret Service on Linux, the login keychain on macOS, the Credential Manager on Windows), one per relay address, never in a file: a `?jwt=` typed into an address moves there when saved. Without a credential store, a relay that needs no token still connects, and saving a token says why it cannot. A setting a flag sets for this run says so, and is not editable there. A change applies the next time you go live. A new relay or token is followed for broadcast sources and guests at once off air, and once the stream ends on air. The recordings folder (Settings, Recording) and the guests' room (Settings, Guests) are kept in the same file, as `recordings`, `room`, `room_key`, `join_page`, `guest_expiry`, and `guests_appear`. ### Settings The gear opens Settings, one window over the pages: the categories down the left, and the one picked on the right. Each line of help names what the setting costs. Escape or a click outside closes it. | Pane | Use it to | | --- | --- | | 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)). | | 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). | On air, a new canvas size or frame rate, or a published scene's new size, asks before it applies, since the video pauses while the new encoders open. The encoders themselves, the sessions open, and each one's work are in the [Health](#health) window. ### Scene graph Settings, Advanced, opens the scene graph in a window of its own: the collection as nodes, each source with a picture or sound, each scene and the always-on-top layers, and each audio scene. A wire runs from each source to every scene or layer placing it, and from each sound and audio scene to every audio scene holding it; one into a scene or clone source shows what it draws, and follows from that source. A wire whose layers are all hidden, or whose sound is muted, is dimmed. Drag from a node's right edge onto a scene's, the always-on-top layers', or an audio scene's left edge to wire them: a picture is placed filling the scene, and a sound or audio scene is sent into the audio scene. Click a wire, then **Remove**, to take every layer of that source out of the scene, or stop the send. Each sound's node has its strip's mute, gain, pan, and delay and a waveform of its last few seconds, each audio scene's node **On program**, **Listen**, and the waveform of its mix, and each scene's node **Safe**, **Publish**, and the audio scene it carries. Clicking a scene takes it on air. Every edit lands in the history, as from anywhere else. ### Published scenes Every scene has a size, the program's unless **Scene sizes**, in Settings, Show, gives it its own, such as 1080x1920 for a portrait scene beside a 1920x1080 program. Every scene is drawn at the program's frame rate. Only a scene of the program's size goes on program: its pad refuses another, saying why, and an edit resizing the scene on air is refused. Switch on **Publish** for a scene, in BUILD's inspector with no layer selected, in the scene graph, or with the **+** of **Publish a scene as its own broadcast** in Settings, Advanced, to put it live as a broadcast of its own beneath the program's, at `/`, at its own size, with renditions and encoders of its own (see [Output](#output)), while the program is on air. A published scene is never switched: it shows what its layers show, whatever is on program. For a portrait stream that follows the program, publish a portrait scene drawing the program through a program source (see [Scene sources](#scene-sources)), with any overlay of its own placed beside it; the always-on-top layers go over the program alone. It carries the audio scene on program, or the one picked beside its **Publish** box, encoded as audio of its own, so picking another never changes the track its viewers play. Unticking it, or removing the scene, ends its broadcast. A published scene's name is one segment of its broadcast path, so it holds no `/`, and a `\` only before another `\`. A scene named `viewers`, where viewers report back, does not publish while live. A source captures or decodes once however many scenes show it. A published scene is drawn only while one of its encoders takes the frame, so with on demand, or off air, one nobody watches costs no drawing. A layer's keyframes play in a published scene from when it was published, picked for recording, or the studio started, whichever came first: a recording and a broadcast of one scene share one picture. ### Scene sources A **scene source** draws another scene as one picture, which a layer places, scales, crops, filters, and blends like any other: a lower third built once and shown in every scene, or a whole layout shrunk into a corner. Add one in BUILD's Add as kind **Scene**, picking the scene it draws, or **Program**, which shows whatever is on air, a transition under way included, on the same frame, such as for a portrait scene that follows the program, cropped. A nested scene is drawn at its own size, transparent where it draws nothing, once per frame however many layers show it, and only while something drawn shows it. Its layers' keyframes play from when the scene showing it goes on, as that scene's own layers' do, so an always-on-top layer, which never goes on, cannot show a scene with keyframes. A media file or overlay in a nested scene set to restart starts over when the scene showing it goes on program. A scene cannot draw itself, even through other scenes, so an edit that would is refused. A scene showing the program cannot go on program, nor can an always-on-top layer show it, since either would draw the program into itself: its pad refuses such a scene, and an edit making the scene on air show the program is refused. Renaming a scene renames what its scene sources draw, and removing one removes them, with the layers showing them. ### Transitions | Transition | What it does | | --- | --- | | Fade | The incoming scene fades in over the outgoing one, at an even pace. | | Slide | The incoming scene pushes the outgoing one off the canvas, both moving left, right, up, or down. | | Wipe | An edge sweeps across the canvas left, right, up, or down, uncovering the incoming scene behind it. | | Move | Each layer showing a source both scenes place glides from its place in the outgoing scene to its place in the incoming one, resizing, recropping, and mixing its filters' settings on the way. If its blend mode or kinds of filter differ, it changes look halfway. The rest of the outgoing scene fades out and the rest of the incoming scene fades in. Layers stack as the outgoing scene has them until halfway, then as the incoming one does. A source placed more than once pairs up in order, back to front. | | Stinger | A media source's clip plays over the program from its start, and the program switches scenes under it at the cut point, the time into the clip when it covers the canvas. It lasts as long as the clip. | A slide, wipe, or move eases in and out. A transition is drawn on the program clock, so the stream and a recording show the same frames of it, and taking another scene while one runs starts from the scene it was heading to. A transition set to 0 ms is a cut. A stinger's clip fills the canvas, cropped evenly to the canvas's shape rather than stretched, through its source's crop and filters, so a clip without an alpha channel can be keyed. The cut point counts from the clip's first picture or sound, however long the file takes to start decoding. Its sound joins the mixes as its source's does. Its source waits blank and silent for the first stinger rather than playing once when it opens, and rests ended between stingers, which the Health window does not count unless a scene on air places it. A clip played to its end holds its last picture, as any media file does, and a looping one stops, blank and silent, after one pass. A clip that cannot play, or that is played again from the inspector or reloaded while a stinger plays it, cuts at once; one stopped there ends the stinger at once. A cut, such as the panic key's, or another kind of transition, while a stinger runs stops its clip, sound included; another stinger plays the clip again from its start. ### Keyframes A layer's keyframes animate it: a layer can fly in, fade in, or blur into focus, and a camera can push in. Each keyframe is a time after the layer's scene goes on and how far the layer is from where it rests then: moved and resized by canvas pixels, cropped further, and drawn through filters after its own. Between two keyframes the layer eases from one to the next, linearly or easing in, out, or (by default) both. Filters of the same kinds, in order, mix their settings, and others change halfway. A keyframe's filters cannot be a LUT or a mask. Set them in the inspector's **Animate** tab: add, time, ease, and remove keyframes, and set how far each moves, resizes, crops, and filters the layer. Keyframes play once, from when the layer's scene goes on program, and hold the last keyframe; before the first, the layer holds the first. A cut or transition starts them again, while a scene leaving in a transition carries on with its own. Press **Play** in the Animate tab to play the scene on program's again from now, or a scene open off air's in its own picture alone. They are drawn on the program clock, so the stream, a recording, and a replay of the program show the same frames. Always-on-top layers have none, since they never go on. Dragging a layer on BUILD grabs it where its keyframes have it and moves where it rests, so its whole animation moves with it. ### Placing layers On BUILD, click a layer of the scene on program, or an always-on-top one, to select it, drag it to move it, and drag its edges or corners to resize it. A drag snaps edges and centers to the canvas's edges and center, to the other layers shown, and to the grid while **Grid** is on, drawing a guide through what it lines up with. A moved layer also snaps to the spacing of its neighbors, marking the equal spaces. Hold Ctrl (Cmd on macOS) to drag without snapping, or turn **Snap** off, in the picture's right-click menu. Resizing a camera, display, window, image, media file, broadcast, or replay keeps its shape, and resizing anything else does not; hold Shift to flip that. Click the picture, then the arrow keys nudge the selected layer a pixel, or ten with Shift held, and a held key undoes as one step; a locked layer stays put. The snap and grid settings are kept per user, with the [hotkeys](#hotkeys), not in the scene file. Layers showing the same source are **linked**: one capture, with the source's look, wherever it is shown. A **clone** is a new source showing another's capture with a look of its own, so a camera can be shown faded in one scene and plain in another while being opened once: **Make independent** and **Duplicate as its own copy** make one. A layer's own crop and filters apply after its source's. Undo (Ctrl+Z) and redo (Ctrl+Shift+Z or Ctrl+Y), in the title bar, step through the history, and a drag undoes as one step; on macOS each shortcut uses Cmd in place of Ctrl. **Copy** (Ctrl+C) takes the selected layer with the source it shows; **Paste** (Ctrl+V) adds it in front of the selected layer's group, or the scene on program, in this studio or another. Pasted where the same source exists under the same name, the layer is linked to it; otherwise the source comes along, renamed if its name is taken. Copied filters paste onto the selected layer, after its own. The clipboard holds text in the scene file's format. ### Dropping and pasting Drag a file from a file manager onto BUILD's picture and it becomes the kind of layer it holds, where you let go: a PNG or JPEG becomes an image layer, and a video or sound file a media layer, each at its own size, no larger than half the canvas, in front of the edited scene, and selected. A sound alone has no picture, so it is only sent to the audio scene on program, as anything with sound is. A `.cube` file grades the layer it is dropped on, in place of any grade it had. While the drag is over the window, the picture outlines where the layer will land and names what it will become, and Add lights that kind. A file dropped on an image or media layer of its own kind asks whether to replace that layer's file, which every layer showing its source shows, or add a layer. Dropped anywhere else in the window, or on another page, it lands in the middle of the edited scene. A file the studio cannot play says why where it was dropped, and how to fix it where it can: a regular MP4 names the remux that makes it readable. The file is read before it is placed, in the background, so a large video holds up nothing while it is read. A dropped file outside the scene file's directory is copied there, since sources name files relative to it: `logo.png`, or `logo 2.png` beside a different `logo.png`, while a copy already there with the same contents is reused. One already under that directory is named where it is. **Paste** (Ctrl+V, or the picture's right-click menu) does the same at the pointer, and the title bar's **Paste** at the scene's center: files copied in a file manager; a picture, such as a screenshot, saved as `Pasted picture.png` beside the scene file; and a web address, as a web page layer the size of the canvas, shown at half that size. The window hears drops on Windows, macOS, and X11. On Wayland it hears none yet, so paste instead; a web address dragged from a browser is not heard on any platform, so paste it too. A broadcast source subscribes through the show's relays, on air or off, over sessions of their own that only subscribe. It plays its broadcast through the first relay while that relay has a route to it, and through the failover otherwise, so a publisher restarted behind only the failover replaces the first relay's copy once that copy ends. It plays the best video and audio its catalog lists, switches when the catalog changes, and comes back on its own when the publisher restarts. While it is offline, or once a new stream replaces the one it played, it shows nothing until the new stream's first picture, rather than freezing on the last one. A broadcast without video but with an image, such as a studio's image or color published independently, shows that image, and never reads as stalled, since it sends a picture only when it changes. A broadcast source, a guest's included, plays on its publisher's timestamps, so its sound and picture stay in sync through network jitter. It plays as far behind what arrives as the network's jitter needs, measured as it goes as `moq play --delay auto` does, plus 50 ms to hand its sound to the mix, up to 2 s in all. When that delay moves, the sound speeds up or slows down by about a tenth until it is back on schedule, as `moq play`'s does, rather than skipping or falling silent: a move of 100 ms takes about a second. A move earlier by more than 200 ms skips, and one later by more than about 130 ms falls silent until the sound is due. Sound and picture each keep that schedule on their own: a sound stall leaves the picture playing, and the sound comes back on the clock, skipping what it missed by more than 200 ms and speeding up through the rest; a picture stall leaves the sound playing, with the canvas showing the last picture meanwhile. Without audio, the picture plays 100 ms behind. The inspector's Source section shows how far behind each broadcast plays. ### Slots and roles A scene can lay out some of its layers by **slots** rather than by hand: one **main** slot, the largest, and **tiles** beside it, in the order of their layers. The scene's **arrangement** places them, each slot 16:9, inside a margin, each picture covering its slot, cropped evenly to fit: | Arrangement | Places | | --- | --- | | Side column | The main slot on the left, the tiles stacked in a column on the right. | | Bottom row | The main slot on top, the tiles in a row under it. | | Grid | Every slot the same size, in as square a grid as fits them. | | Picture in picture | The main slot fills the canvas, the tiles small, stacked up from its bottom-right corner. | A layer in a slot closes up when it has nothing to show: when it is hidden, when its source is offline or failed, or when it shows a role nothing fills. The others grow into its room, and they glide there over 0.4 s on program, as a Move transition does, so a guest joining or leaving moves the rest rather than cutting them. Layers set free, by their own `rect`, stay where they are, so a scene can mix both: a backdrop behind the slots and a logo over them. A **role** is a source that names another, once for the whole show: `Main`, the main picture, or `Camera`, the host's camera. A layer showing a role shows its source, through that source's crop and filters, and filling the role with another source, from the scene inspector's Slots or the layer's Source section, changes it in every scene at once. A role filled by nothing draws nothing, and its slot closes up. Removing the source filling a role leaves the role unfilled. A role takes no look of its own, and is not cloned or published; its layers take their own. The scene inspector's **Slots** section picks the arrangement, lists the slots with the role or source in each and what fills each role, and adds a **Main slot** or **Camera slot**, making the role if the show has none. Add, under **Not in any scene**, puts a guest into the scene's next tile when it has slots. **Appear on their own**, in Settings, Guests, has a guest whose camera comes online take the next tile of the scene on program, and be heard on program, as an edit you can undo. Up to four guests still in the room take tiles that way, and more wait under Add. One who leaves keeps their tile, closed until they are back, and frees their place: the next guest takes a new tile, or once four tiles hold guests, a tile the studio gave one who has left. They are no longer heard on program unless another layer shows them, and wait under Add when back, as they appeared once already. A tile you gave a guest yourself stays theirs, as does a copy of one, and the scene file marks the studio's own with `auto = true`. A guest appears on their own once per link, across restarts: after that, where they are shown is yours, so undoing their appearance or removing their layer keeps them off when they reconnect, until a new link. Since an appearance is your edit, it drops what you could redo. Off, every guest waits under Add, as before. ### Keeping out of the way A scene's layer with **Keep out of the way** on, in the inspector's Place section, moves itself off what matters in the picture under it, such as a facecam off a game's minimap or a slide's text. A few times a second the studio draws the layers under it, scaled far down, and reduces them on the GPU to a grid: where the picture moves, where it is dense with edges that hold still, as text is, and what holds still while the rest moves, as a HUD does. Each can be switched off under **Stays clear of**. Nothing is uploaded: the choice is made on this machine, from the picture alone. It moves to one of eight places, the canvas's corners and edge middles, inside a margin of a twentieth of the canvas's shorter side, that its size fits in, taking the one that covers the least of what matters, a corner over a middle that covers as much. It chooses a second after its scene goes on, about two seconds after the content under it changes kind (another layout, or another app), and otherwise moves only once its place has been the worst of them for 10 seconds, never for a single busy moment. It moves only to a place that covers clearly less, so over a picture where nothing matters it stays where it rests, even outside the eight places. What it covers is where its keyframes draw it, and it never goes where they would draw it off the canvas. It glides to a new place as a move transition eases, in 0.4 s unless **Glide** says otherwise. Its rect in the scene file gives its size, and where it rests until it first moves. While it is selected, BUILD shows what it saw: what matters glowing, tagged **MOVING**, **TEXT**, or **HUD**, the places it may go, dashed, and where it last moved from, with what it left there and an arrow to where it went. Drag it, nudge it, or type its X or Y, and it stays where it was put until the content changes, as it does where a redo or a reload of the scene file moves it, or an undo moves it anywhere but back before such a move. Undo that move and it goes back to where it was, such as the corner it had glided to. A resize keeps it free to move. Switched off, it stays where it is drawn, and undoing that puts it back keeping clear where it was. Only a scene's layer set free of its [slots](#slots-and-roles) keeps out of the way, and not one showing a source [published independently](#published-independently), which viewers place themselves; putting one in a slot switches it off. While the show goes out in [both formats at once](#both-formats-at-once), it moves only in the landscape picture: in the portrait one it stays at the place set there, or fitted from where its rect rests. ### Both formats at once A landscape show can go out in portrait too, for phones, beside the landscape picture for desks and TVs: switch on **Both at once** in Settings, Show. Each scene of the show's size then has two arrangements of the same layers, and the studio draws, encodes, and sends both pictures. A scene of its own size, such as a published portrait scene, stays one picture, in its own shape, the same in both down to the scenes it shows, so it cannot go on program meanwhile. A scene given the show's size as its own follows the show's size instead when you turn it on. Turning it on is one edit you can undo, and starts each portrait arrangement from the landscape one. The largest picture, covering a quarter of the canvas or more, is the main one: it is cropped to the top 60% of the portrait canvas, with the largest camera stacked under it, cropped to fill the rest, or fitted there keeping its outline if it has a round or rounded shape. Without a camera, the main picture covers the whole portrait canvas. A backdrop covering the landscape canvas covers the portrait one, cropped, but a web page or overlay covering it, mostly see-through, is fitted whole and is never the main picture. What sits on the main picture, such as a lower third or a logo, keeps its place on it. A layer set anywhere else keeps its place on the turned canvas, scaled to fit. A scene laid out by slots arranges them in a row in portrait, or in a grid or inset if that is how it arranges them in landscape, and picks its own portrait arrangement in BUILD's scene inspector. A layer showing another scene of the show's size, or the program, shows that scene's portrait arrangement in the portrait picture, tall as the portrait canvas is, so its place there is shaped for it: one covering the landscape canvas, such as a scene of overlays, covers the portrait canvas whole rather than being the main picture, and one set anywhere else keeps its place, as wide and as much taller as its picture turned. Giving that scene a size of its own in Settings, or the show's back, changes the shape of its picture there, so each layer showing it is fitted inside the place it had in the portrait picture, in the same edit. LIVE shows both pictures side by side, each in its tally frame, with its format, size, and what its video sends under it. BUILD edits one picture at a time: **Landscape** or **Portrait** under the picture picks which, and the other shows small beside it, where a click edits it instead. A drag, Fit, Fill, the inspector's X, Y, W, H, and crop all place the layer in the picture edited, and leave its place in the other alone, even one fitted there from its landscape place. A layer in a slot has one crop in both. Each scene's pad shows the pair, and Studio mode's NEXT card shows both pictures of the scene cued. A layer is shown in both pictures, or only in one: **Format** in its inspector, and the chip under the pictures naming the selected layer, picks **Both**, **Landscape**, or **Portrait**. A layer shown only in landscape keeps no portrait place. Switching **Both at once** off removes every layer shown only in portrait and forgets every portrait place and arrangement, as one edit. Only a landscape canvas turns: picking Portrait in Settings, Show, switches Both off. The portrait picture goes out as its own broadcast, at `/portrait` (see [Output](#output)), so a published scene cannot be named `portrait` meanwhile. ### Audio scenes Audio from every source is mixed whether or not its scene is live, and cuts never change it. A collection has one or more **audio scenes**, each the sum of the sounds it holds and of the audio scenes it holds: for example a "Mics" audio scene holding every microphone, which both a "Stream" audio scene (Mics, without music you may not broadcast) and a "Headphones" one (Mics and the music) hold. A sound an audio scene reaches more than one way plays in it once, and an audio scene never holds itself, even through others. Add, rename, reorder, and remove audio scenes on the MIX page. The MIX page is a mixing desk. Each sound has a strip: its name, a meter, a fader for its gain in decibels (unity is marked, and a double click returns to it), its gain to read or type, and its mute, which turns amber while it is on. These apply in every audio scene holding the sound. Click a sound's name to open its strip to its gain, pan (a double click centers it), and delay, and the audio scenes it is heard in; the other strips narrow beside it rather than hide. Each audio scene has a strip after the sounds with **Listen** and its meter, on the same scale, which reads the audio scene as **Listen** plays it, published sources included. A meter's top is full scale, where its last segment turns red: the sound clips. Under each strip is a dot for each audio scene, marked with its initial: filled where the strip is sent into it, the accent's color for the one the stream carries; ringed where it is heard there only through another audio scene; and faint where it is not heard. A click sends it in or takes it out. An audio scene shows a dash under its own strip and under any it holds, which it cannot be sent back into. A sound [published independently](#published-independently) keeps its dots and sends: they say where people in the studio hear it, while viewers hear it from its own broadcast and the audio the studio encodes leaves it out. **Routes** shows the same sends as a matrix, a row for each sound and audio scene and a column for each audio scene, with what each one holds at its foot. A source added from BUILD's Add, or pasted, is sent to the audio scene on program, so it is heard at once. The audio scene on program is tagged **Stream hears this**; **Put on stream** on another's strip puts that one on program instead, and switching it, or editing an audio scene, never drops or repeats audio. **+** after the audio scenes adds one, holding nothing. Right-click an audio scene's strip, or its column under **Routes**, to rename it, move it left or right, or remove it. A recording holds the audio scene on program unless Settings, Recording picks another, such as one keeping music the stream leaves out, which is tagged **In the recording**, and each published scene carries the one on program unless BUILD's inspector picks another beside its **Publish** switch; switching either while it runs never drops or repeats audio either. The audio scene on program cannot be removed; removing one a recording or published scene picks returns it to the one on program. **Listen** on an audio scene's strip plays it to an audio output, from the `capture` feature's build: the system default, or the one picked from the tag on the strip while it plays, which the studio remembers for you rather than in the scene file. Use headphones: a microphone that hears the speakers feeds its audio scene back into itself. A source's **delay** holds it back in every audio scene, up to 2 s, so a microphone lines up with a camera that lags it. A broadcast's picture already follows its sound, so its delay holds the sound back from its own picture: use it only for a publisher whose sound leads their picture. Each audio scene is mixed on the program clock, and each output reads its audio scene on its own, so an output that falls behind skips ahead in its own audio rather than holding up the mixing or another output. A browser source renders a web page, such as an overlay, alert box, or chat widget, at the canvas frame rate (CEF caps it at 60) over a transparent background, and its sound joins the audio scenes that hold it. Every page shares one browser profile, kept in `$XDG_DATA_HOME/moq-studio/browser` (`~/.local/share/moq-studio/browser` by default) rather than beside the scene file, so cookies and logins, such as an alert service's, survive a reload and a restart of the studio. They are not encrypted with the desktop's keyring, so a locked keyring never holds a page back, and anything that can read your home directory can read them. One studio at a time can use the profile: a second one's browser sources fail saying so. Each page renders in a process of its own, so a page that crashes fails only its own source, with the reason, while the stream carries on. A crash of the browser itself fails every browser source. Either shows at once, since the browser's processes dump no core. On Linux, pages run without Chromium's sandbox, as in OBS, so a page that exploits a browser bug can do anything you can: add only pages you trust. The browser requests only what its pages load, never asking Google for updates, the time, or autofill suggestions on its own, so pages are not spellchecked, which would need a dictionary from Google. Nor does it run browser extensions, even ones your distribution installs for every Chromium. **Reload** in Sources restarts a page, failed or not. A page's dropdown lists, such as a `