--- name: cast description: Use SuperScreencast to compose a screen and camera, record local video with cut and resume, control a virtual camera or microphone for calls, configure RTMP/RTMPS streaming, and apply privacy pause through its verified Linux CLI. --- # SuperScreencast Use this skill for the SuperScreencast desktop application. SuperScreencast Community is MIT licensed and includes recording, streaming and the virtual camera. SuperScreencast Pro is a separate edition. Do not infer current entitlements from older marketing copy. Check `cast edition --json`, `cast features --json`, and `cast --help` before changing a user's setup. Public branding is SuperScreencast; the `cast` / `cast-pro` commands, source repositories, configuration paths, skill identifier, and internal license identifiers remain unchanged. This reference was verified against SuperScreencast 0.10.0 CLI help and the source README, `docs/cli.md`, `docs/configuration.md`, `docs/streaming.md` and `examples/cast.conf`. The full reference is https://github.com/mattmezza/cast/blob/main/docs/cli.md. Commands act on the existing daemon through a user-only Unix socket. A timeout means completion is unknown: inspect `cast status --json` before repeating a start action. Runtime commands change session state; they never write configuration back to disk. ## Build and install The source uses GNU make, not Meson. Read the source README for distro dependencies. A C compiler, GNU make, pkg-config, FFmpeg development libraries, PipeWire, Fontconfig, FreeType and a system font are required. Xorg needs Xlib/Xext/XRandR/XInput2/XFixes/XComposite; Wayland needs GLib GDBus (`gio-unix-2.0`). The optional panel requires SDL3 and SDL3_ttf; Clay is vendored. ```sh git clone https://github.com/mattmezza/cast.git cd cast make -j X11=1 WAYLAND=1 PANEL=1 ./cast --version ./cast config check examples/cast.conf ./cast doctor sudo make install X11=1 WAYLAND=1 PANEL=1 PREFIX=/usr/local ``` Install only when asked. For a Wayland-only build, use `X11=0 WAYLAND=1`. A headless build omits `PANEL=1`. `make uninstall PREFIX=/usr/local` removes a manual installation. Official dynamically linked packages require matching runtime dependencies; `cast setup` prints advice without modifying devices or configuration. Copy the sample only for a new configuration; preserve existing user settings: ```sh mkdir -p "$HOME/.config/cast" cp -n examples/cast.conf "$HOME/.config/cast/cast.conf" cast config check "$HOME/.config/cast/cast.conf" ``` ## Daemon, panel and preview ```sh cast --headless # In another terminal: cast panel cast preview on cast status --json ``` `cast --headless` runs the daemon in the foreground for terminals/services. There is no `cast daemon` command. Bare `cast` starts or attaches through the panel. `cast panel` is attach-only, with a Start control when stopped. Closing the panel or preview leaves capture and outputs running. `cast quit` stops the daemon and finalizes recordings. Startup may open the physical camera and light its LED even while virtual output is privacy-paused; neutral transmitted video does not mean no source capture. Configure before revealing: ```sh cast layout overlay cast camera anchor bottom-right cast camera size 22% cast camera mirror off cast preview target virtual ``` Layouts are `overlay`, `stage`, `split`, `screen`, `camera`; `cast layout next` and `cast layout prev` cycle the configured order. Use `cast capture window select`, `cast capture region select` or `cast capture monitor` where the backend supports them. Inspect status instead of assuming acquisition succeeded. ## Virtual camera and microphone An existing v4l2loopback device is required. Do not create privileged devices automatically. `cast setup` and `cast doctor` show the required setup for the actual machine. ```sh cast virtual start # producer starts with a solid privacy screen cast virtual resume # deliberately reveal the composition cast audio list cast audio mic source SELECTED_PIPEWIRE_SOURCE cast audio mic on cast audio virtual on cast virtual pause # solid frame and silence cast virtual stop cast audio virtual off ``` Replace `SELECTED_PIPEWIRE_SOURCE` with a source discovered through `cast audio list`; do not guess. Select the virtual video device named “Cast” and the virtual microphone separately in the call app. SuperScreencast cannot mute a physical microphone selected directly by that app. Desktop audio is off by default and requires an explicit source; enabling it can include conference participants. Pause, blur and freeze silence SuperScreencast's virtual audio. ## Local recording, cut and countdown Use a new local file path; existing files are never overwritten. Set a session countdown with the real configuration key: ```sh cast settings record.countdown 3 cast record start /absolute/path/cast-test.mkv cast status --json cast record cut cast record resume cast record pause cast record resume cast record stop cast status --json ``` `record cut` omits interruption time from the same file. Resume from cut reuses the countdown and preserves prior solid/freeze/blur flags. `record pause` instead writes a solid pause screen and silence. `record stop` also cancels an initial countdown. Wait for `record.finalizing` to become false before using the file or starting another. Escape or closing the temporary countdown preview cancels a pending start/resume. `cast record cancel` cancels a pending action; it does not represent recording finalization. For recording without virtual video, start a fresh daemon with `cast --headless --no-virtual`. Add `--no-camera` and choose `cast layout screen` for screen-only capture. Do not restart an active daemon without understanding its ongoing outputs. ## Streaming configuration and safe start A stream key is a secret. SuperScreencast accepts its **absolute file path**, never an inline key, URL suffix or configuration value. The file must be regular, owned by the user, not a symlink and mode 600. A user can create the empty file and enter the secret in their editor: ```sh install -d -m 700 "$HOME/.config/cast" install -m 600 /dev/null "$HOME/.config/cast/stream.key" # The user enters the key privately; agents never request or display it. ``` Example configuration, with non-secret placeholder server and an absolute local path: ```ini [stream] service = custom server_url = rtmps://your-ingest.example/app key_file = /home/you/.config/cast/stream.key video_bitrate_kbps = 2500 audio_bitrate_kbps = 128 encoder_preset = veryfast ``` INI does not expand `~` or shell expressions. `cast config reload` applies supported changes; destination/encoder changes require streaming stopped. To explain a user-authorized broadcast, these are the exact commands; do not execute public broadcasts as an agent: ```sh cast stream start # connects and transmits a solid pause screen cast stream status --json cast preview target stream cast stream resume # explicit reveal cast stream pause # connection continues, solid screen and silence cast stream stop ``` Starting paused still contacts the destination and transmits media. Stream status reports local writes and lifecycle, not viewer delivery. `cast stream blur on`, `cast stream unblur`, `cast stream freeze` and `cast stream unfreeze` affect an existing stream independently. Resume clears solid pause only. Streaming has no cut command. Stop cannot retract transmitted media or control service buffering. ## Privacy ```sh cast pause cast resume cast virtual pause cast record pause cast stream pause ``` Global pause remembers only the solid-pause flags it changes and cancels pending recording countdowns. Resume restores those flags; it never starts a stopped output, clears recording cut, or reveals an independently paused lane. Blur may leave information recognizable; freeze holds captured content. Use solid pause for privacy. ## Configuration The default is `$HOME/.config/cast/cast.conf`. A startup `--config /absolute/path/cast.conf` selects another file. Precedence is defaults, file, startup flags, then session commands. Validate first: ```sh cast config check /absolute/path/cast.conf cast config defaults cast config reload cast settings output.pause_title "Back soon" output.pause_subtitle "{date:%A} {time:%H:%M}" ``` Example persistent settings (merge with the user's file, never overwrite it): ```ini [output] backend = wayland device = /dev/video10 width = 1920 height = 1080 fps = 30 pause_title = Back soon pause_font = Noto Sans [camera] device = /dev/video0 anchor = bottom-right width_percent = 22 mirror = false [composition] layout = overlay layout_order = overlay,stage,split,screen,camera [record] directory = /home/you/Videos countdown = 3 ``` `output.pause_font` and `output.blur_font` are config-only. Paths/device names above are examples to replace. Do not enable all-key annotations without explicit intent: they can expose passwords and private typing. ## Troubleshooting - Run `cast doctor`, `cast config check` and `cast status --json` first. These are the source of concrete errors and backend capability reporting. - Wayland needs PipeWire and a working desktop screen-cast portal; monitor selection opens compositor consent. Window/region selection and exclusion are backend-dependent. Never promise transparent exclusion. - Xorg uses its native capture libraries. Panel/preview overlap on monitor/region capture is masked with `capture.mask_color`; hidden desktop content is not reconstructed. Capturing a selected application naturally excludes unrelated windows. - Virtual video needs the existing v4l2loopback device, matching kernel headers/module and user permissions. With `exclusive_caps=1`, consumers may list it only after the producer starts. Device creation requires a separate user-authorized privileged setup. - PipeWire microphone/desktop sources require explicit selection. A disappeared source becomes silent; there is no broader-source fallback. Conferencing audio/video selection is separate. - A panel unavailable error means SDL3/SDL3_ttf or the `PANEL=1` build is missing. The daemon and CLI remain usable headlessly. - A conflicting older `/usr/local/bin/cast` can shadow a packaged `/usr/bin/cast`. Check `command -v cast` and `cast --version` before diagnosing commands. ## Safety Agents must not start public broadcasts or use real credentials. Test recording to a new local file instead. Do not silently reveal a privacy-paused output, enable broad desktop audio, install privileged kernel devices, overwrite configuration, or stop a user's ongoing recording. Explain actual output state and obtain the user's instruction before those actions.