# LumaCast

A small native Windows streaming studio built around a software-rendered editor,
isolated window capture and an isolated FFmpeg encoder. No game injection,
Electron shell or embedded browser runtime.

## Start

1. Extract the entire portable ZIP on a Windows 10 (version 2004 or newer) or Windows 11 x64 PC.
2. Open `LumaCast.exe`. The .NET runtime and FFmpeg are included.
3. Let the local encoder check finish. Auto tests AMD AMF, NVIDIA NVENC or Intel
   Quick Sync when detected then falls back to CPU encoding.
4. Select Gameplay. Choose the display or visible game window in Capture Source.
5. Add text, PNG/JPEG images or color blocks. Select a layer to drag it. Drag its
   bottom-right corner to resize it. Use Up/Down to change stacking order.
6. Enable the desired audio channels before starting output. Meters run during
   output. Microphone is off by default. Device changes require stopping output.
7. Use Record locally and check the MKV in Videos/LumaCast.
8. Open Connection + devices and paste your Twitch primary stream key. Use a
   bandwidth test with Twitch Inspector first. Then disable test mode and click
   Go live on Twitch when you are ready.

An empty stream key can be saved to clear the stored key. Test mode resets when
the app closes. A stream is never started automatically.

## Import from OBS

In OBS use Scene Collection > Export to save a JSON collection. In LumaCast click
Import OBS scenes and choose the JSON file. Select one or more scenes and read
the import report before adding them. Existing LumaCast scenes are kept.

The importer brings across scene order, layer order, visibility, ordinary image
sources, basic text, color sources and simple nested scenes/groups. It scales
positions and sizes to LumaCast's 1280 x 720 canvas. Images are copied into the
studio assets folder. Text metrics and complex layouts need visual review.

Capture sources become disabled capture layers with estimated dimensions. Select
the layer, choose the correct display/window in its source dropdown, adjust the
size and enable Visible in output. This avoids accidentally capturing the wrong
display when moving to another PC. Game capture uses isolated Windows window capture after relinking to a window.

Browser alerts, webcam/media sources, source filters, rotations, mirroring,
cropped sources and some bounds modes are reported as unsupported. Unsupported
cropped sources are skipped entirely. OBS audio routing, transitions and hotkeys
are not imported. A review report is saved in the LumaCast settings directory.
The original OBS file is never modified. Images must be available on a local
drive. For an older export without resolution metadata enter its original base
canvas size in the import dialog before reading it again.

## Lightweight clips

No Twitch account or broadcast is needed.

- Record locally provides ordinary manual start/stop recording to MKV.
- Select Last 30s or Last 60s then click Buffer clips to begin rolling capture.
- Save clip exports the completed buffer into an MP4 in your recording folder.
- Ctrl+Alt+R starts/stops the buffer. Ctrl+Alt+S saves a clip while the game has focus.
- Clip saving uses stream copy. It does not run another video encode and does not
  interrupt the buffer. The file can be played or shared immediately.
- Clips use completed two-second segments. The latest incomplete segment is
  excluded and the start is rounded to a segment boundary, so the result can
  start up to two seconds earlier and end up to two seconds before the button press.
- During warmup a shorter clip is saved. At least one completed segment is needed.
- Only the recent encoded segments plus a small margin are retained on disk.
  At the default bitrate the current buffer is roughly 16 MB for 30 seconds or
  30 MB for 60 seconds. Export briefly needs another buffer-sized snapshot plus
  the saved clip. A normal stop removes the temporary buffer and keeps saved clips.
- Buffering still continuously captures and encodes video. Turn Preview off for
  less editor work. Stop the buffer when you no longer need it.
- Buffering, manual recording and Twitch streaming are separate output modes.

## Scenes and controls

- Starting soon, Gameplay and Be right back are included and fully editable.
- Scene and overlay changes apply immediately to active output.
- Ctrl+Alt+1 through Ctrl+Alt+9 switches scenes even while the game has focus.
- Ctrl+Alt+0 and Quick break switch to a capture-free break scene and mute both
  audio channels. Unmute explicitly when you return.
- Recording and streaming are separate output modes in this version.
- Uncheck Preview to save additional work during a broadcast.
- Window sources use Windows Graphics Capture. Other windows placed over the game
  are excluded. Display sources intentionally include everything on that display.
  Keep the game open and not minimized. Use borderless/windowed mode. Protected
  content and exclusive fullscreen may appear blank. Windows shows a capture border.
  An unavailable window shows the scene background, never a desktop fallback.
- The LumaCast window is excluded from screen capture on supported Windows builds.

## Hardware-aware behavior

Auto starts shared AMD/Intel graphics at 960 x 540 / 30 fps / 2200 kbps. Dedicated
hardware defaults to 1280 x 720 / 30 fps / 3500 kbps. The GPU-name heuristic is
conservative; choose Low impact for 640 x 360 / 30 fps / 1200 kbps on any machine.
Audio is 160 kbps stereo AAC with two-second video keyframes. The encoder must
pass its local test before selection. CPU compatibility starts at 540p and uses
at most two encoder threads. FFmpeg filter work is limited to one thread.

The editor uses WPF software rendering. Window capture uses a two-frame Windows
Graphics Capture pool with one reusable readback texture. If the GPU is busy it
reuses the last available image instead of blocking on readback. Composition is
on the CPU. During output the 5 fps editor preview shares the output capture;
it does not capture the game a second time. Minimize LumaCast or turn Preview off
to skip thumbnail generation. Audio and output frame buffers are reused.
FFmpeg runs below normal process priority.

Short timing delays reuse frames to catch up without repeating expensive capture.
Both audio and video use one session clock. Sustained capture pressure reduces
resolution while retaining hardware encoding first. Network errors reconnect
with the same profile and bounded backoff up to 30 seconds. Encoder faults can
fall back to CPU. A healthy minute resets the consecutive encoder-failure budget;
there is no three-failure lifetime limit. Repeated failures at the lowest settings
still stop with a diagnostic message rather than loop endlessly.

Changing profile reconnects Twitch and can briefly interrupt playback. Adaptation
is not an upload-speed test or seamless dynamic bitrate. Local recording failure
still stops and reports an error instead of silently splitting files. Diagnostics
include a resource/frames/compose-time summary once a minute. These are measurements
of LumaCast, not a measurement of the game's FPS.

If AMD encoding remains unstable select CPU compatibility. Window capture still
uses Windows' graphics capture path, so this is not a guarantee against a driver
fault. Try Low impact first if the game slows down while capturing.

## Privacy and state

- Settings, assets and rotating diagnostics live in `%LOCALAPPDATA%/LumaCast`.
- Scene saves use atomic replacement. Invalid settings are preserved with an
  `.invalid-<timestamp>` suffix before the defaults are loaded.
- Imported images are copied into the app's assets folder.
- Twitch keys are encrypted with Windows DPAPI for the current Windows account.
- Stream URLs and keys are redacted from logs. The FFmpeg process necessarily
  receives its output URL in process arguments, which local privileged process
  inspection can see.
- Output uses RTMPS to Twitch. There is no telemetry or cloud configuration.
- A Windows job object terminates FFmpeg if the editor exits unexpectedly.
- Stop closes the media pipes and gives FFmpeg time to finalize MKV recordings.

## Current boundaries

This is an early version, not complete OBS feature parity. Webcam capture,
embedded browser alerts, animated/media sources, audio filters, transitions,
simultaneous streaming and recording plus Twitch chat/OAuth are
not implemented. Capture has been tested locally. The specific AMD integrated
GPU rig and an authenticated Twitch broadcast still need a real session.

## Build and validate

Requires the .NET 10 SDK and Windows. Run from PowerShell:

```powershell
.\scripts\build.ps1
```

The script downloads a pinned FFmpeg 9.0.2 essentials build, verifies its SHA-256,
publishes a self-contained app, runs local tests and creates a portable ZIP.
Build output and external binaries are ignored by Git. `-SkipTests` is available
for iteration; the delivered release is built with tests enabled.

To run tests separately:

```powershell
.\dist\LumaCast-0.5.0\LumaCast.exe --self-test --report C:\Temp\lumacast-test.json
```

Self-tests use an isolated profile, generated scenes and a synthetic audio tone.
They never connect to Twitch or read the real stream key. Test media and the
rendered UI are retained beside the report for inspection.

## References

- [Twitch broadcasting guidelines](https://help.twitch.tv/s/article/broadcasting-guidelines?language=en_US)
- [FFmpeg documentation](https://ffmpeg.org/ffmpeg-all.html)
- [FFmpeg Windows download providers](https://ffmpeg.org/download.html)
- [NAudio WASAPI loopback capture](https://github.com/naudio/NAudio/blob/release/2.x/Docs/WasapiLoopbackCapture.md)
- [OBS scene collections](https://obsproject.com/kb/scene-collections)
- [OBS scene transform implementation](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-scene.c)


## Updates

LumaCast 0.4.0 checks zzyx.de for updates at startup. The Updates button shows a
new version when one is available. Choose Download and restart to install it.
Stop streaming, recording and clip buffering first. A failed automatic check
never interrupts output; use Updates to retry and see the result.

The updater accepts only the official HTTPS download URL and verifies the exact
size and SHA-256 before extracting. It rejects unsafe archive paths and keeps
a previous installation beside the portable folder. If folder activation fails
it restores the previous folder. Scenes and the encrypted Twitch key remain in
%LOCALAPPDATA%\LumaCast. Keep the portable folder somewhere writable such as
Downloads or your user Applications folder. No administrator permission is needed.

The previous folder and downloaded update are retained for recovery. After you
have checked the new version you can remove its adjacent .previous-* folder and
%LOCALAPPDATA%\LumaCast\updates contents while LumaCast is closed.
Version 0.3.0 and earlier need one manual download to get this updater.


## Connection recovery in 0.5.0

Twitch streaming automatically reconnects after a network drop, router reconnect
or remote session end. Retries wait 2, 4, 8, 16 then at most 30 seconds between
attempts and continue until you press Stop. A silent output stall is detected
within 18 seconds. Session cleanup can take up to another five seconds.
The studio shows RECONNECTING with a countdown, then returns to LIVE ON TWITCH
when encoded output resumes. Network recovery keeps your selected quality,
scene and audio mute settings. Explicit encoder faults still use codec recovery.
Local recordings stop on failure so their saved-file status remains clear.

Recovery reconnects the stream after internet access returns. It cannot supply
video during an outage or guarantee that Twitch preserves the same broadcast
session. Version 0.5.0 also embeds the mint L icon in the executable and windows
for the taskbar, Alt+Tab and Explorer.