# RavenMix technical manual

Early-access edition · Draft 0.4 · Last updated October 12, 2026

## About this manual

RavenMix is actively developed. This manual describes existing operator workflows and separately identifies development updates and remaining work. Documentation updates do not mean a new application build has shipped. Check the release notes for the build you are running before relying on a newer behavior.

The source targets Apple silicon and declares macOS 15 as its minimum. On-device captions require macOS 26 or later. A complete supported-hardware matrix and first-time-user walkthrough remain in progress.

## Product and development status

| Status | What it means here |
|---|---|
| Existing workflows | Preview/Program switching, scenes, local camera and audio capture, Network Device Interface (NDI) sources, Zoom participant inputs, Program recording, selective isolated recording, embedded recording timecode and virtual-camera video. Availability depends on the build, installed components and permissions. The chapters explain operation; they do not certify every device or workload. |
| Tested development changes | Improved audio-device reconnection and recovery limits; recording audio-continuity handling and warnings. These have code-review and generated-test evidence, with specific hardware observations below. They are not a blanket release or production-readiness claim. |
| Under investigation | Frame loss when recording several isolated video sources at once, recording-load capacity, remaining audio-level/timing issues, and complete recording failure/recovery behavior. |
| Planned | An opt-in machine-capacity check, broader protocol coverage, further interoperability and long-show qualification. Planned items are not available features. |

## Development journal — newest first

### October 12, 2026

- **Recording diagnostics built; review pending.** The new development candidate separates writer refusal from other dropped-frame causes and counts losses before frames reach the Program recorder. All 107 automated tests passed. A short generated comparison used six video writers at mixed 30 and 60 frames per second; all twelve resulting movies decoded with the expected picture sequence. These were small 320-by-180 test frames, so this is correctness evidence, not proof of six-camera high-definition capacity.
- **A recording-load limitation reproduced.** In approximately three-minute tests with the same reported Program source, isolated recording off produced zero Program writer drops; enabling five isolated video recordings produced 339 drops and visible gaps in saved frames. Encoding, scheduling and storage contributions are still being distinguished. No safe maximum source count has been established.
- **Automatic audio reconnection progressed.** A reviewed development build recovered the same Yamaha audio device automatically across three unplug/reconnect cycles while recording continued. This is a specific test result, not certification of every interface or interruption. Remaining recording and audio-quality acceptance work is still open.
- **Capacity check proposed.** After the current investigation, we plan an optional test that estimates a conservative recording workload for a user's Mac, selected drive, codecs and frame rates. It will include Program and audio workload, provide headroom and state its limits. This feature is not implemented.

### October 9, 2026

The first public manual was published with operating guidance, chapter navigation, print support and a Markdown download. Local development updates added recording audio-continuity behavior. Later development builds and the limitations above supersede assumptions based only on that first documentation edition.

## Known limitations and practical guidance

- **Recording capacity:** do not assume every selected source can be recorded without loss. Test the intended full workload, recording drive and duration before a show; review both Program and separate files afterward. All sources and new arrivals default to selected in the selective-recording build, but selection is not proof of successful capture. Recording selection does not put a source into Program.
- **Audio recovery:** video continuing and audio meters returning do not prove complete or clean recorded audio. Missing source audio cannot be recreated. Automatic reconnect is not guaranteed for a device that returns under a different identity. Recovery pauses after a bounded number of automatic attempts in the reviewed recovery candidate; explicit refresh or reconnection may be needed.
- **Recording warnings:** very small timing gaps can inflate warning counts in current development recordings; that correction remains separate work. Warning persistence after stopping, isolated-audio gap handling, failure finalization and stop-tail behavior remain review or acceptance items. Inspect the actual saved media.
- **Synchronization:** embedded timecode is available in the timecode-enabled builds, but it does not prove cross-device lip sync or eliminate drift. Physical cue tests, editor imports and longer recordings remain necessary.
- **Virtual camera:** the camera output is video. The receiving application's microphone/audio route must be configured separately; a working picture does not prove a digital audio feed.
- **Remote control:** authentication and browser-access hardening remain review findings. Do not expose the remote-control service to the public Internet; this manual is not a security qualification.
- **Protocols and experimental work:** Secure Reliable Transport (SRT), Real-Time Streaming Protocol (RTSP) camera input and Open Sound Control (OSC) are not advertised as available workflows here. Media eXchange Layer (MXL) work remains experimental and is not a released networking feature.
- **Release qualification:** sustained high-load recording, storage failures, broader device compatibility, accessibility and clean-install acceptance are incomplete. Short generated tests and successful builds do not close those gaps.

## 1. Production concepts

**Preview** is the source or scene prepared for the next switch. **Program** is the current production picture used by the output paths. A **scene** arranges one or more sources with layout and graphics.

**Isolated (ISO) recording** saves selected individual sources alongside the Program recording. Recording selection is independent of what is on screen. A newly discovered source can join isolated recording without appearing in Preview, Program or a scene.

Recording, streaming and virtual-camera output have separate controls. Verify each output's own status; a moving Program picture does not prove that a stream is reaching its destination or that an audio file is being written.

Basic signal flow:

```text
Video sources → scenes / switching → Program → recording / streaming / virtual camera
Audio sources → mixer → Program mix → Program recording / streaming
Selected source video and pre-fader audio → separate recordings
```

The virtual camera supplies video. Configure the receiving application's microphone separately; starting the virtual camera does not automatically send RavenMix audio to it.

## 2. Setup and first recording

### Prepare

1. Install the intended release in Applications and read its build-specific notes. Release packaging and local development builds have different verification status.
2. Open RavenMix. In the Welcome sheet, allow camera and microphone access, choose a recording folder and review virtual-camera setup if needed.
3. Confirm the recording destination has enough free space. Capacity depends on codec, resolution and the number of recordings; the Program estimate is not a guarantee for all separate files combined.
4. Open **Cameras**, select a source for Preview and confirm motion. Set the audio input and confirm the intended channels have activity.
5. Prepare Preview, then press **CUT** to put it in Program. Confirm both the picture and intended audio mix.
6. Save a named show before the production.

### Make a short acceptance recording

1. In Output, confirm format, codec and destination.
2. If separate recordings are wanted, enable **ISO**, then open **Sources…**. Review the selected sources before starting.
3. Press **Record**. Check Program recording status and the individual source statuses.
4. Capture visible motion and an audible test signal. If testing a remote participant, check both the meeting application and RavenMix.
5. Stop recording and allow finalization to finish. Review **Last recording** for warnings.
6. Open the saved Program file and selected source files in an editor or player. Check the beginning, middle and end for picture, sound, duration and synchronization.

This test does not qualify a long show or crash recovery. For an important production, complete the required acceptance tests and maintain an independent recording until the build has earned that trust.

## 3. Sources and remote guests

### Local cameras and audio devices

Use **Cameras** for devices exposed to macOS as cameras. Select the audio input separately in the Audio panel; a camera picture alone does not establish an audio route. Device permissions, vendor software and physical connections can affect availability.

### Network video

**Network Device Interface (NDI)** sources appear in the NDI tab when the runtime, sender and network discovery are working. Runtime packaging depends on the build. A picture in an encoder's browser dashboard proves that dashboard path works; it does not prove RavenMix has discovered or decoded the network source.

For a missing source, check sender output settings, the receiving Mac's network connection, source discovery and receiver status. Document the actual incoming dimensions and motion when accepting a device. A receiver compatibility matrix and illustrated troubleshooting procedure remain to be written.

### Zoom guest input

The guest bridge brings meeting participants into RavenMix as sources. It requires the configured Zoom Meeting software development kit (SDK) integration and the meeting permissions needed for receiving participant media. Receiving guests is a different workflow from selecting RavenMix Camera in Zoom to send Program video outward.

1. In **Zoom**, enter the meeting details or use **Paste Invite**.
2. Join and obtain the host's recording permission as required by the meeting configuration.
3. Confirm each intended participant appears and has moving video in RavenMix.
4. Add the intended participant to a scene or switch them to Program explicitly.

When a guest leaves and rejoins, their source identifier may change. **Reconnect Zoom source** lets the operator select the returning guest for a missing scene source. This replaces that source across all scenes, including Program, while retaining scene layout. Verify identity before choosing; the change can immediately affect the on-air picture. The app does not infer that matching display names identify the same person.

Reconnection, freezing and quality-request behavior remain active acceptance areas. See the release notes for the exact repaired build and outstanding limitations.

## 4. Switching, scenes and graphics

| Control | Action |
|---|---|
| CUT / Return | Instantly swap Preview and Program. |
| TAKE / Space | Dissolve Preview into Program using the selected transition duration. |
| FADE TO BLACK / Command-B | Fade Program to black, or restore it. |
| Record / Command-R | Toggle Program recording; review armed sources first. |

Keyboard focus can affect shortcuts while editing text. Practice the controls in the intended workspace before going live.

Build a scene from the supplied layouts, adjust its sources and geometry, and check it in Preview. Missing sources and reconnect choices must be resolved deliberately. Titles, lower thirds, chat overlays and captions can appear over Program; treat featuring a chat message as an on-air action.

Detailed scene-editing illustrations, graphic sizing, caption setup, chat setup and transition examples will be added after a matched-build walkthrough. Stinger transitions and automatic video-following-audio are not documented as available features in this edition.

## 5. Audio routing

The Program mix is the audience mix. **Monitor** is the listening output. **Mix-minus** is a return mix with designated return sources excluded, used to avoid feeding a guest's own sound back to them.

Select the intended input, include the required channels in Program, set their levels and listen to the result. Use meters to confirm activity, but use headphones and a saved test file to establish that routing is correct. Keep return paths out of themselves; a device appearing in both directions is not automatically a safe routing configuration.

With selective isolated recording enabled, individual audio is captured **before mute, solo and fader adjustments**. Muting a channel in the live mix does not exclude its separate recording. Use **Sources…** before the take to exclude it. Audio devices can be opened for recording independently of the selected Program input.

Advanced routing diagrams, channel-link/pan reference, level-setting examples and validated console configurations remain documentation work. Do not assume automatic noise reduction, dynamics or drift correction.

### Audio continuity — check your build

Audio-continuity-enabled builds reserve a stereo 48,000-sample-per-second audio track even when no source is ready when you press Record. A source arriving later can join that recording. With a selected input unavailable, the standby mixer continues other available sources and contributes silence for the missing input. The Audio panel shows **Input unavailable — other audio continues** and clears the warning when valid input resumes. A soloed missing input stays silent in the monitor.

Short callback timing gaps are filled to preserve the audio timeline. Recovery discards overlapping old input samples rather than replaying them. Source mute, selection, faders and mix-minus settings still apply. This preserves the Program mix; it does not create missing audio in individual-source recordings. Sleep, major system stalls, physical reconnects and long shows still need acceptance testing. Always inspect the finished recording and keep an independent backup for important productions.

## 6. Recording and timecode

### Selecting sources

In the selective-recording build, all available sources default to selected. New devices and guests are automatically added during a take, subject to availability and permissions. Explicit exclusions remain for the current session; do not assume exclusions survive an application restart. A returning guest with a new identifier is a new source and can be automatically selected.

Manual source-selection changes are disabled during a take. Discovered audio-device channels appear as media arrives. Read **Waiting**, **Recording**, missing-media and failure/overflow states separately; “selected” is not proof of a usable file.

### Files

Program is a `.mov` recording. Separate files are stored in the companion folder whose name ends in `_ISO`.

| File | Contents in the selective-recording build |
|---|---|
| Program movie | Program video and the available Program audio mix. |
| Individual video movie | Source video without embedded reference audio. |
| Individual audio movie | Separate 24-bit uncompressed pulse-code modulation (PCM) audio, before live-mix controls. |

Physical-device channels are recorded separately and represented as duplicated mono in a two-channel file. Other source feeds may be stereo. Do not interpret every two-channel file as two independent microphones. Earlier builds may embed Program-reference audio in individual videos; keep the originating build with any handoff.

No-media outputs are not usable recordings and should not be counted merely because a source was selected. Review partial/error status before handing files to another product.

### Embedded timecode — included in local build 202610090800

Program, individual video and individual audio use one frozen correlation between local time of day and the Mac's monotonic clock. Each file's first media timestamp determines its start label. Late sources therefore retain their offset within the take rather than all beginning with the same label.

Every file uses the take's Program timecode rate, even when source video has a different cadence. Fractional rates use exact frame durations of 1001/24000, 1001/30000 or 1001/60000 seconds. The convention is **non-drop-frame (NDF)**: labels advance at the media rate and wrap after 24 nominal hours. At fractional rates they intentionally diverge from wall-clock time during a long take. Later clock adjustments do not reseed the take.

Timecode is embedded in a QuickTime `tmcd` track and finalized on normal stop. It is not a complete recording-set manifest, a crash-recovery guarantee or sample-accurate cross-device synchronization. Remote transport latency and clock drift are not corrected by adding labels. External **linear timecode (LTC)** input/output is not part of this repair.

Keep originals and source associations together. CloudRecords import and alignment are being developed separately; automatic complete-set synchronization is not promised by this manual.

## 7. Streaming and virtual camera

### Streaming

**Real-Time Messaging Protocol (RTMP)** and encrypted RTMP (RTMPS) output are implemented for one destination. Open Stream Settings, choose the destination, enter its server address and stream key, and choose the intended bitrate. The key is stored in the Mac's Keychain.

Run a controlled destination test before a show. Start Stream, then verify the destination's own preview and audio. Stop Stream explicitly when finished. The current implementation does not provide a qualified automatic-reconnect or simultaneous multi-destination workflow. YouTube account sign-in and broadcast creation are not implemented; manual stream-key output is a separate feature.

**Secure Reliable Transport (SRT)** input/output and **Real-Time Streaming Protocol (RTSP)** camera input are not implemented in the reviewed source. Do not treat a bundled library or older guide wording as feature availability.

### Virtual camera

Install/enable RavenMix Camera through RavenMix and the approval flow shown by macOS. Start the virtual-camera output, then select RavenMix Camera in the receiving application. If it is absent after installation, reopen that application and check extension approval/status. System Settings wording varies with operating-system version.

Confirm the actual picture in the receiving application. Configure and test its audio separately. A virtual-camera update can require another approval or restart; consult the release notes.

## 8. Remote control

The control **application programming interface (API)** and browser remote normally listen on this Mac at `http://127.0.0.1:8088`. Settings → Remote Control controls availability, port and access from other devices.

Other devices require an access code. A control code permits commands; a viewer code allows the read-only views exposed by the server. Local loopback requests have full access. The current transport is plain Hypertext Transfer Protocol (HTTP); an access code does not encrypt network traffic. Use a trusted production network and do not expose this service directly to the public internet.

Use the command reference provided with your build for commands. The browser remote does not imply certification of a dedicated Companion or Stream Deck plug-in. Check feedback and reconnect behavior before relying on a control surface during production.

## 9. Shows and workspace

Save a show with a descriptive name and use the show indicator to notice unsaved changes. Save templates deliberately. Saving a show is not the same as copying its referenced media, recording files or credentials into a portable package.

Panels can be arranged, locked and opened separately. Rehearse the layout with the actual displays and control surfaces. Save before changing machines or updating RavenMix. An unsaved-show prompt should be resolved before an update closes the app.

A complete show-file field reference, portability procedure and missing-media recovery guide remain to be validated.

## 10. Troubleshooting and support

| Symptom | First checks |
|---|---|
| No camera or microphone | Welcome sheet, macOS permissions, device connection and selected input. |
| Encoder browser works but network source does not | Sender protocol/output, runtime, network discovery and actual receiver status. |
| Zoom guest visible in Zoom but absent in RavenMix | Guest identity, bridge status, recording permission and the current guest/source state. |
| Scene breaks after guest rejoin | Use the explicit reconnect control after verifying the returning guest; it can affect Program. |
| Separate source file is absent | Source selection, actual media arrival, permissions, last-recording status and destination. |
| Muted source is still in its separate audio recording | Expected pre-fader behavior; exclude it in Sources before the take. |
| Recorded audio ends before video | Preserve the original, note the build and source setup, and report it. This is an unresolved investigation; do not assume new timecode repairs it. |
| Stream does not reach its destination | Server address, key, destination readiness, app status and destination preview. |
| Virtual camera absent | Approval state, started output and receiving-application restart. |

Help includes **Report a Problem…**, **Copy Diagnostics** and **Show Log Folder**. Problem reporting prepares a diagnostic archive and an email workflow. Review the contents and message before sharing: diagnostics can include device/source names, paths and operational state even when credentials are not intended to be included. Never paste meeting secrets or stream keys into a report.

A useful report states the build, operating system, expected result, actual result, reproduction steps, approximate time and whether the saved file is affected. Keep captured media private unless its sharing is explicitly approved.

## Documentation status

This is an evolving early-access manual. The dated journal above records development and known limitations; it does not announce an application release. Screenshots, illustrated procedures, supported-device coverage and release-specific acceptance remain in progress.

For help or corrections, contact [support@happyjack.media](mailto:support@happyjack.media). Include your build and the relevant section; do not send stream keys or meeting credentials.