Unity-FFmpeg-ScreenRecorder

A Windows and macOS Unity package that wraps a bundled ffmpeg/ffmpeg.exe to record the desktop, a microphone/system audio input, or a specific Camera, and to merge separately-recorded audio/video files.

Installation

Add the package via Unity Package Manager (Add package from git URL):

https://github.com/shinn716/Unity-FFmpeg-ScreenRecorder.git?path=Packages/com.shinn.ffrecorder

Requirements:

• Windows or macOS. All four components launch ffmpeg as a subprocess; they will fail on Linux/mobile. The platform is detected automatically at runtime via Application.platform — no manual switch needed.
• ffmpeg binary. Import the "StreamingAssets (Windows)" or "StreamingAssets (macOS)" sample matching your target platform from the Package Manager window (or copy the matching StreamingAssets-windows~/StreamingAssets-macos~ contents) into Assets/StreamingAssets so Application.streamingAssetsPath + ffmpegPath resolves to a real executable.
• macOS only: unsigned binary. The bundled ffmpeg isn't code-signed, so Gatekeeper blocks it on first run. After copying it into Assets/StreamingAssets, run once from a terminal:

  xattr -d com.apple.quarantine Assets/StreamingAssets/ffmpeg/ffmpeg
  

  The executable bit (chmod +x) is set automatically at runtime the first time a recorder launches ffmpeg, so that step doesn't need to be done manually.
• UniTask. Pulled in automatically as a package dependency (com.cysharp.unitask), no manual setup needed.

Setup

1. Add one of FFScreenRecorder, FFAudioRecorder, FFFrameRecorder, or FFMergeAV to a GameObject.
2. For FFScreenRecorder/FFAudioRecorder, click the Scan button next to the AudioInput field (or run GetDevicesList from the component's context menu) once — this queries ffmpeg for available audio devices (dshow on Windows, avfoundation on macOS) and turns AudioInput into a dropdown. Device names are platform-specific: switching from Windows to macOS (or vice versa) means re-scanning and picking a name from that platform's list, since a name like Built-in Microphone only exists on macOS.
3. Pick the audio device from the dropdown.
4. Click Start Recording/Stop Recording (or Start Merge for FFMergeAV) directly in the Inspector, or call StartRecording()/StopRecording() from script/UI. The Inspector also shows whether the bundled ffmpeg binary was found, live recording status/elapsed time, and an Open Output Folder shortcut. The finished file's path is available on GetOutputName once stopping completes.

macOS notes

• FFScreenRecorder.captureSize/offsetPos are ignored on macOS — the desktop capture device (avfoundation) always captures the full screen, unlike Windows' gdigrab which supports a cropped region.
• FFScreenRecorder.captureMouseCursor (draw the OS cursor in the recording) only works on Windows (-draw_mouse). ffmpeg's avfoundation equivalent (-capture_cursor 1) crashes the bundled macOS ffmpeg build's screen input, so it isn't wired up there — the cursor is never shown in macOS recordings.
• FFmpegPreset.H264Nvidia/HevcNvidia require an NVIDIA GPU and only work on Windows.

Components

FFScreenRecorder

Captures the desktop together with an audio input into a single video file — gdigrab+dshow on Windows, avfoundation on macOS.

Field	Meaning
ffmpegPreset	Output codec/container (H.264, HEVC, ProRes, VP8/9, HAP, ...)
framerate	Output/capture framerate (FFmpegFramerate enum: 24/25/30/50/60/120)
captureSize	Capture region size in pixels; (0, 0) captures the full desktop. Windows only.
offsetPos	Top-left offset of the capture region. Windows only.
captureMouseCursor	Draw the OS mouse cursor in the recording. Windows only, see macOS notes above.
AudioInput	Audio device name (dropdown after scanning)

screenRecorder.StartRecording();
// ... later
await screenRecorder.StopRecording(); // awaitable: completes once the output file is finalized

FFAudioRecorder

Captures a single audio input (dshow on Windows, avfoundation on macOS) to an .mp3 file. Same AudioInput scan/dropdown as above.

FFFrameRecorder

Captures frames from a target Camera (not the desktop) at framerate, encoding them into a video once stopped. Set TargetCam before calling StartRecording() — it no-ops with a log message otherwise.

FFMergeAV

One-shot: combines an existing video file (VideoOutput) and audio file (AudioOutput) into a single .mp4 via StartMerge(). Typically used to combine FFFrameRecorder's silent video with a separately-recorded FFAudioRecorder track.

Output files

All components share:

• OutputFolder — folder name created under StreamingAssetsPath.
• CustomFileName — if empty, files are named <ProductName>_<yyyyMMdd_HHmmss>. Invalid filesystem characters are replaced with _, and _1, _2, ... is appended if a file with the same name already exists, so a previous recording is never overwritten.

Recording flow

flowchart TD
    A["Add FFScreenRecorder / FFAudioRecorder / FFFrameRecorder to a GameObject"] --> B["Click Scan next to AudioInput (or right-click -> GetDevicesList)"]
    B --> C["Pick AudioInput from the scanned device dropdown"]
    C --> D["StartRecording / StartMerge"]
    D --> E["BuildOutputFilePath: sanitize CustomFileName, append _1/_2 if the name already exists"]
    E --> F["Launch ffmpeg.exe with the recorder's arguments"]
    F --> G{"Recorder type"}
    G -->|FFScreenRecorder| H["Windows: gdigrab desktop + dshow audio; macOS: avfoundation -> video file"]
    G -->|FFAudioRecorder| I["Windows: dshow; macOS: avfoundation -> mp3 file"]
    G -->|FFFrameRecorder| J["Capture Camera frames to temp JPGs each tick"]
    J --> K["StopRecording: cancel the capture loop"]
    K --> L["Await all pending JPG writes"]
    L --> M["Encode JPG sequence -> video via ffmpeg image2"]
    H --> N["StopRecording: send 'q' to ffmpeg stdin"]
    I --> N
    N --> O["ffmpeg finalizes the output file"]
    M --> P["Output file in StreamingAssets/OutputFolder"]
    O --> P
    P --> Q["FFMergeAV: combine a video file + an audio file -> merged mp4"]

Loading

Need to set Audio input in first time.

• FFAudioRecorder Capture microphone and system sound.

• FFFrameRecorder Capture camera frames without audio.

• FFMergeAV Merge Audio(mp3) and Video(mp4).

• FFScreenRecorder FFmpeg Capture screen and audio (speaker and microphone) Click Start Recording in the Inspector (or right-click the component and click StartRecording), it will capture screen and audio both. Then click Stop Recording, it will stop recording and export video to StreamingAssets/Output.