### Audio Capture Usage Example

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Demonstrates how to configure, create, initialize, and start the AudioReader, and retrieve its time base for synchronization.

```cpp
#include "audio.hpp"
#include "frame-writer.hpp"

// Configuration
AudioReaderParams audio_params;
audio_params.audio_backend = "pipewire";
audio_params.sample_rate = 48000;
audio_params.audio_frame_size = 2048;
audio_params.audio_source = nullptr; // use default

// Create and start audio capture
std::unique_ptr<AudioReader> audio_reader(AudioReader::create(audio_params));
if (audio_reader && audio_reader->init()) {
    audio_reader->start();
    
    // Synchronize with video capture
    uint64_t audio_start = audio_reader->get_time_base();
}
```

--------------------------------

### Install wf-recorder from Source

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

After building, install wf-recorder using Ninja.

```bash
sudo ninja -C build install
```

--------------------------------

### Install Dependencies on Ubuntu

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Install necessary development packages for building wf-recorder on Ubuntu.

```bash
sudo apt install g++ meson libavutil-dev libavcodec-dev libavformat-dev libswscale-dev libpulse-dev
```

--------------------------------

### Examples of Audio Device Selection

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Examples demonstrating how to enable audio recording with default device, a specific device name, or a loopback device.

```bash
wf-recorder -a                           # Auto-detect device
wf-recorder --audio=speaker_loopback     # Record speaker output
wf-recorder -a mic_input                 # Record microphone
```

--------------------------------

### Examples of B-frame Configuration

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Examples showing how to configure B-frames for low-latency streaming and high-quality encoding.

```bash
# Low-latency streaming (no B-frames)
wf-recorder -b 0 -c libx264

# High-quality (more B-frames)
wf-recorder -b 3 -c libx265
```

--------------------------------

### Build wf-recorder from Source

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/README.md

Steps to clone the repository, configure the build using Meson, and install the utility.

```bash
git clone https://github.com/ammen99/wf-recorder.git
cd wf-recorder
meson build --prefix=/usr --buildtype=release
ninja -C build
sudo ninja -C build install
```

--------------------------------

### Install wf-recorder on Void Linux

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Use this command to install wf-recorder on Void Linux using xbps.

```bash
xbps-install -S wf-recorder
```

--------------------------------

### Examples of VAAPI Device Specification

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Examples demonstrating how to specify the device for Intel and AMD GPUs, and the preferred auto-detection method.

```bash
# Intel GPU
wf-recorder -c h264_vaapi -d /dev/dri/renderD128

# AMD GPU  
wf-recorder -c h264_vaapi -d /dev/dri/renderD130

# Auto-detect (preferred)
wf-recorder -c h264_vaapi
```

--------------------------------

### Install Dependencies on Fedora

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Install necessary development packages for building wf-recorder on Fedora.

```bash
sudo dnf install gcc-c++ meson wayland-devel wayland-protocols-devel ffmpeg-free-devel pulseaudio-libs-devel
```

--------------------------------

### Install wf-recorder on Debian

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Use this command to install wf-recorder on Debian-based systems using apt.

```bash
apt install wf-recorder
```

--------------------------------

### wf-recorder Framerate Examples

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Examples show setting specific framerates for different video styles, such as 24fps for a film look or 60fps for smooth capture.

```bash
wf-recorder -r 24 -f cinematic.mkv    # 24fps film style
wf-recorder -r 30 -f video.mp4         # 30fps standard
wf-recorder -r 60 -f smooth.mkv        # 60fps smooth capture
```

--------------------------------

### Build wf-recorder from Source

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Clone the repository, configure the build with Meson, and build using Ninja. Installation is optional.

```bash
git clone https://github.com/ammen99/wf-recorder.git && cd wf-recorder
meson build --prefix=/usr --buildtype=release
ninja -C build
```

--------------------------------

### Install Dependencies on Void Linux

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Install necessary development packages for building wf-recorder on Void Linux.

```bash
sudo xbps-install -S meson ninja gcc pkg-config scdoc wayland-devel wayland-protocols wayland-devel libgbm-devel libdrm-devel ffmpeg6-devel x264-devel pulseaudio-devel pipewire-devel
```

--------------------------------

### Display Help Message

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Show the help message with usage examples for all command-line options.

```bash
wf-recorder --help
wf-recorder -h
```

--------------------------------

### wf-recorder Codec Parameter Examples

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Examples show setting specific codec parameters for high-quality encoding with libx264, bitrate control for VP9, and quality settings for VAAPI.

```bash
# High quality with slower encoding
wf-recorder -c libx264 -p preset=slower -p crf=16 -f hq.mkv

# VP9 with bitrate control
wf-recorder -c libvpx-vp9 -p bitrate=5000 -f video.webm

# VAAPI with quality
wf-recorder -c h264_vaapi -p rc_mode=1 -p qp=25
```

--------------------------------

### Install wf-recorder on Fedora

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Use this command to install wf-recorder on Fedora using dnf.

```bash
dnf install wf-recorder
```

--------------------------------

### Install wf-recorder on Alpine Linux

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Use this command to install wf-recorder on Alpine Linux using apk.

```bash
apk add wf-recorder
```

--------------------------------

### Example CLI Commands for Recording Scenarios

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/INDEX.md

Demonstrates various command-line options for different recording scenarios, including basic recording, high quality, GPU acceleration, audio inclusion, region capture, and streaming.

```bash
# Basic recording
./wf-recorder -o output.mp4

# High quality recording
./wf-recorder -o high-quality.mp4 -x yuv420p -r 60 -b 10M

# GPU-accelerated encoding (VAAPI)
./wf-recorder -o gpu-accelerated.mp4 -c h264_vaapi -d /dev/dri/renderD128

# Recording with audio
./wf-recorder -o audio-video.mp4 -a alsa -C hw:0

# Region recording
./wf-recorder -o region.mp4 -g 100,100,800,600

# Streaming to stdout
./wf-recorder -f pipe:1 -c libx264rgb -r 30
```

--------------------------------

### Configure and Build wf-recorder with PipeWire

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/configuration.md

Clone the repository, configure the build with PipeWire as the default audio backend and libx265 as the default codec, then build and install.

```bash
# Clone and enter directory
git clone https://github.com/ammen99/wf-recorder.git
cd wf-recorder

# Configure with PipeWire as default audio backend
meson build \
  --prefix=/usr \
  --buildtype=release \
  -Ddefault_codec=libx265 \
  -Ddefault_audio_backend=pipewire

# Build
ninja -C build

# Install
sudo ninja -C build install
```

--------------------------------

### Basic wf-recorder Usage Examples

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/README.md

Common command-line options for recording, listing outputs, specifying files, regions, and audio.

```bash
# Record default output
wf-recorder
```

```bash
# Record with filename
wf-recorder -f recording.mkv
```

```bash
# List available outputs
wf-recorder -L
```

```bash
# Record specific output
wf-recorder -o HDMI-1 -f hdmi_output.mkv
```

```bash
# Record region (with slurp)
wf-recorder -g "$(slurp)"
```

```bash
# With audio
wf-recorder --audio -f with_audio.mkv
```

```bash
# GPU-accelerated (VAAPI)
wf-recorder -c h264_vaapi -d /dev/dri/renderD128 -f gpu_encoded.mkv
```

--------------------------------

### Start RTSP Server and Stream with gstreamer

Source: https://github.com/ammen99/wf-recorder/wiki/Home

This command starts an RTSP server and streams video and audio using gstreamer. It specifies audio sample rate, video resolution, and framerate. The `./test-launch` program is part of the gst-rtsp-server repository.

```bash
wf-recorder -a -R 48000 -o DP-2 -y -c h264_vaapi -m rawvideo -D -r 15 -f /dev/stdout | ./test-launch '( fdsrc fd=0 ! decodebin ! videoconvert ! video/x-raw,format=I420,width=1920,height=1080 ! x264enc tune="zerolatency" byte-stream=true ! rtph264pay name=pay0 pt=96 autoaudiosrc ! audioconvert ! avenc_aac ! rtpmp4gpay name=pay1 pt=97 )'
```

--------------------------------

### Install wf-recorder on Arch/Artix Linux

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Use this command to install wf-recorder on Arch or Artix Linux using pacman.

```bash
pacman -S wf-recorder
```

--------------------------------

### PipeWireReader Initialization and Start

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Initializes the PipeWireReader, setting up the PipeWire thread loop and context. Use this when PipeWire is the desired backend.

```cpp
bool PipeWireReader::init() override;
```

```cpp
PipeWireReader* pw = new PipeWireReader();
pw->params.sample_rate = 48000;
pw->params.audio_frame_size = 2048;
pw->params.audio_source = "example_source_name";
if (pw->init()) {
    pw->start();
}
```

--------------------------------

### Examples of FFmpeg Filter Usage

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Examples demonstrating common FFmpeg filter applications, including scaling, GPU resizing, and format conversion.

```bash
# Downscale to 720p
wf-recorder -F "scale=1280:720"

# GPU resize with NV12 format
wf-recorder -c h264_vaapi -F "scale_vaapi=format=nv12"

# Rotate and downscale
wf-recorder -F "transpose=1,scale=1280:720"

# Format conversion only
wf-recorder -F "format=yuv420p"
```

--------------------------------

### Check FFmpeg Libraries

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/errors.md

Verify the installation of FFmpeg libraries. This is a prerequisite for compilation.

```bash
ffmpeg -version
```

--------------------------------

### PulseReader Initialization and Start

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Initializes the PulseReader, connecting to PulseAudio and preparing for audio capture. Use this when PulseAudio is the desired backend.

```cpp
bool PulseReader::init() override;
```

```cpp
PulseReader* pr = new PulseReader();
pr->params.sample_rate = 48000;
pr->params.audio_frame_size = 4096;
pr->params.audio_source = nullptr;
if (pr->init()) {
    pr->start();
} else {
    delete pr;
}
```

--------------------------------

### Check Wayland Development Files

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/errors.md

Verify the installation of Wayland development files using pkg-config. This is a prerequisite for compilation.

```bash
pkg-config --list-all | grep wayland
```

--------------------------------

### Check Audio Backend Libraries

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/errors.md

Verify the installation of necessary audio backend libraries like libpulse-simple, pulseaudio-libs, or libpipewire-0.3. This is a prerequisite for compilation.

```bash
pkg-config libpulse-simple pulseaudio-libs libpipewire-0.3
```

--------------------------------

### Core API Usage Example

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/INDEX.md

Illustrates the fundamental steps for using the wf-recorder API to capture frames, including initialization, frame writing, and cleanup.

```c++
#include <wf-recorder/FrameWriter.hpp>
#include <wf-recorder/AudioReader.hpp>
#include <wf-recorder/buffer_pool.hpp>

// ... initialization code ...

// FrameWriter and AudioReader setup
FrameWriterParams params;
params.output = "output.mp4";
params.input_format = InputFormat::RGBA;
params.width = 1920;
params.height = 1080;

FrameWriter writer(params);
AudioReader *audio = AudioReader::create(AudioReaderParams{});

// Capture loop
while (true) {
    // Capture frame
    buffer_pool_buf *buf = buffer_pool.get_buffer();
    // ... fill buf with frame data ...
    writer.write_frame(buf);

    // Capture audio
    // ... read audio data ...
    // writer.write_audio(audio_data, num_samples);

    // Check for exit condition
    if (should_exit()) {
        break;
    }
}

// Cleanup
writer.close();
delete audio;

```

--------------------------------

### Check GBM/DRM Libraries

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/errors.md

Verify the installation of GBM/DRM libraries using pkg-config. This is a prerequisite for compilation.

```bash
pkg-config --list-all | grep gbm
```

--------------------------------

### PulseReader start Method

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Spawns a background thread to continuously read audio frames from PulseAudio and submit them.

```cpp
void PulseReader::start() override;
```

--------------------------------

### wf-recorder Codec Examples

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Demonstrates common codec usage with wf-recorder, including H.264, H.265, and GPU-accelerated options like h264_vaapi.

```bash
wf-recorder -c libx264 -f video.mp4        # H.264 default settings
wf-recorder -c libx265 -p preset=slow -p crf=16  # Better quality
wf-recorder -c h264_vaapi -d /dev/dri/renderD128 # GPU encoding
```

--------------------------------

### wf-recorder Pixel Format Example for VAAPI

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

This example demonstrates converting the pixel format to NV12, which is commonly used with h264_vaapi for GPU encoding.

```bash
# Convert to NV12 for GPU encoding
wf-recorder -c h264_vaapi -x nv12 -F "scale_vaapi=format=nv12"
```

--------------------------------

### Example Nginx RTMP Configuration

Source: https://github.com/ammen99/wf-recorder/wiki/Home

This is an example configuration block for nginx to handle RTMP streams. Ensure the 'application feed' directive matches the stream path used by wf-recorder.

```nginx
rtmp {
        server {
                listen 1935;
                chunk_size 4096;

                application feed {
                        live on;
                        record off;
                }
        }
}
```

--------------------------------

### DMA-BUF Device Detection Example

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/INDEX.md

Shows how DMA-BUF feedback is used for device detection in Wayland integration, crucial for GPU buffer handling.

```c++
// Inside wf-recorder's Wayland integration

// Request frame with DMA-BUF
screencopy_request_frame(screencopy_manager, output, ...);

// ... later, in frame_ready callback ...

if (frame->buffer_flags & WF_BUFFER_DMABUF) {
    // Access DMA-BUF file descriptors and metadata
    int fd = frame->dmabuf_fd;
    uint32_t width = frame->dmabuf_width;
    uint32_t height = frame->dmabuf_height;
    uint32_t format = frame->dmabuf_format;
    uint32_t stride = frame->dmabuf_stride;

    // Use these to import the buffer into the GPU (e.g., via EGL or Vulkan)
    // This allows direct GPU access without CPU copies.
}

```

--------------------------------

### Example of Synchronizing Output Information

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/wayland-integration.md

Demonstrates the usage of `sync_wayland()` to ensure that output geometry and position events are processed before proceeding.

```cpp
zxdg_output_manager_v1_get_xdg_output(...);
// ... add listeners ...
sync_wayland();  // Ensure logical_position/size events processed
```

--------------------------------

### Basic Screen Recording

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Start a basic screen recording. The output will be saved as 'recording.mp4' in the current directory. Press Ctrl+C to stop.

```bash
wf-recorder
```

--------------------------------

### Install wf-recorder on NixOS/Nix

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Add wf-recorder to your NixOS configuration or use nix-shell, nix shell, or nix run for temporary access.

```bash
nix-shell -p wf-recorder
```

```bash
nix shell nixpkgs#wfrecorder
```

```bash
nix run nixpkgs#wf-recorder
```

--------------------------------

### Basic Invocation of wf-recorder

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Starts screen recording of a Wayland output. Press Ctrl+C to stop.

```bash
wf-recorder [OPTIONS]
```

--------------------------------

### start

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Creates a PipeWire stream connected to the audio source with stereo 32-bit float format. If `params.audio_source` is specified, searches the registry for the matching source by name. Audio is captured via SPA callbacks that write to internal buffers and submit to `FrameWriter`.

```APIDOC
## start

### Description
Creates a PipeWire stream connected to the audio source with stereo 32-bit float format. If `params.audio_source` is specified, searches the registry for the matching source by name. Audio is captured via SPA callbacks that write to internal buffers and submit to `FrameWriter`.

### Method
void

### Parameters
None
```

--------------------------------

### Basic wf-recorder Usage

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/configuration.md

Start a recording using the wf-recorder command-line tool. Specify the output file path with the -f flag. Recordings can be stopped by pressing Ctrl+C.

```bash
wf-recorder [OPTIONS] -f <output_file>
```

--------------------------------

### Sway Key Bindings for wf-recorder

Source: https://github.com/ammen99/wf-recorder/wiki/Usage-with-Sway

Configure Sway's config file to add key bindings for starting and stopping wf-recorder. Use these to record the full screen, a selected area, or to stop active recordings.

```bash
bindsym Ctrl+Print exec wf-recorder -f ~/recording_$(date +"%Y-%m-%d_%H:%M:%S.mp4")
bindsym Ctrl+Shift+Print exec wf-recorder -g "$$$(slurp)" -f ~/recording_$(date +"%Y-%m-%d_%H:%M:%S.mp4")
bindsym Ctrl+Shift+BackSpace exec killall -s SIGINT wf-recorder
```

--------------------------------

### AudioReader Base Class start Method

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Pure virtual method to begin capturing audio. Usually spawns a background thread to read audio data.

```cpp
virtual void start() = 0;
```

--------------------------------

### Start PipeWire Audio Capture

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Creates a PipeWire stream connected to the audio source with stereo 32-bit float format. If `params.audio_source` is specified, searches the registry for the matching source by name. Audio is captured via SPA callbacks that write to internal buffers and submit to `FrameWriter`.

```cpp
void PipeWireReader::start() override;
```

--------------------------------

### Get Codec-Specific Options

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

To find available options for a specific FFmpeg encoder, use the 'ffmpeg -h encoder=<codec_name>' command.

```bash
ffmpeg -h encoder=libx264
ffmpeg -h encoder=h264_vaapi
```

--------------------------------

### Specify Video Codec with wf-recorder

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Use the -c or --codec flag to specify the video codec for recording. Examples show setting libx265 and h264_vaapi.

```bash
wf-recorder -c libx265 -f output.mkv
wf-recorder --codec=h264_vaapi
```

--------------------------------

### AudioReader Base Class get_time_base Method

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Returns the starting timestamp for audio synchronization with video. Used to align audio and video frames.

```cpp
virtual uint64_t get_time_base() const { return 0; }
```

--------------------------------

### Example: Advancing Encode Buffer in Loop

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/buffer_pool.md

Demonstrates how to call `next_encode()` within an encoding loop after successfully adding a frame. This ensures the pool moves to the next available buffer for subsequent encoding.

```cpp
// In encode loop
bool success = frame_writer->add_frame(buffers.encode().data, 
                                       buffers.encode().timestamp, 
                                       buffers.encode().y_invert);
if (success) {
    buffers.next_encode(); // Move to next frame
}
```

--------------------------------

### Setting up Virtual Audio Sources

Source: https://github.com/ammen99/wf-recorder/wiki/Home

Create a virtual null sink and use loopback modules to combine multiple audio sources (mic and application sounds) before capturing them. Replace 'alsa_*' with your actual source names.

```bash
pactl load-module module-null-sink sink_name=Combined
```

```bash
pactl load-module module-loopback sink=Combined source=alsa_output.pci-0000_00_1f.3.analog-stereo.monitor
```

```bash
pactl load-module module-loopback sink=Combined source=alsa_input.pci-0000_00_1f.3.analog-stereo
```

--------------------------------

### Core API: FrameWriter Initialization and Usage

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/README.md

Demonstrates preparing FrameWriter parameters, creating a writer instance, and submitting video and audio frames.

```cpp
#include "frame-writer.hpp"
#include "audio.hpp"

// Prepare frame writer
std::atomic<bool> abort_flag{false};
FrameWriterParams params(abort_flag);
params.file = "output.mkv";
params.codec = "libx264";
params.width = 1920;
params.height = 1080;
params.stride = 1920 * 4;
params.format = INPUT_FORMAT_BGR0;
params.framerate = 60;
params.enable_audio = true;
params.audio_codec = "aac";
params.sample_rate = 48000;

// Create writer
FrameWriter writer(params);

// Submit video frames
uint8_t* frame_buffer = /* pixel data */;
int64_t timestamp_usec = /* frame time */;
bool success = writer.add_frame(frame_buffer, timestamp_usec, false);

// Optional: audio
size_t audio_size = writer.get_audio_buffer_size();
uint8_t audio_buffer[audio_size];
// Fill audio_buffer
writer.add_audio(audio_buffer);

// Cleanup on exit
// writer destructor flushes and closes file
```

--------------------------------

### List Available Sample Formats

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

List all available FFmpeg sample formats.

```bash
ffmpeg -sample_fmts
```

--------------------------------

### Select Audio Capture Backend

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Choose the audio capture backend. Use `pipewire` for modern systems or `pulse` for older ones. Errors if the selected backend is unavailable.

```bash
wf-recorder --audio --audio-backend=pipewire -f output.mkv
wf-recorder -a --audio-backend=pulse
```

```bash
# Force PipeWire (modern systems)
wf-recorder -a --audio-backend=pipewire

# Force PulseAudio (older systems)
wf-recorder -a --audio-backend=pulse
```

--------------------------------

### Initialize FrameWriter

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/FrameWriter.md

Configure and initialize the FrameWriter with output file, codec, dimensions, and format. Throws on failure.

```cpp
std::atomic<bool> abort_flag{false};
FrameWriterParams params(abort_flag);
params.file = "output.mp4";
params.codec = "libx264";
params.width = 1920;
params.height = 1080;
params.stride = 1920 * 4;
params.format = INPUT_FORMAT_BGR0;
params.framerate = 60;
params.enable_audio = false;

FrameWriter writer(params);
```

--------------------------------

### Handle PipeWire Initialization and Source Errors

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/errors.md

Check the return value of `init()` for PipeWireReader. If `false`, PipeWire initialization failed, and audio recording is skipped. Errors related to finding audio sources are logged as warnings, and the system attempts to use a default.

```cpp
if (init() == false) {
    // Audio recording skipped, video continues
    // Logs error, falls back to silent recording
}
// Warning logged, uses default
// Non-fatal, continues with default source
```

--------------------------------

### buffer_pool::buffer_pool

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/buffer_pool.md

Initializes the buffer pool. It starts with 2 pre-allocated buffers and can grow up to the specified capacity N.

```APIDOC
## buffer_pool::buffer_pool

### Description
Initializes the pool with 2 buffers pre-allocated. The pool can grow up to `N` buffers as needed.

### Method
```cpp
buffer_pool();
```

### Example
```cpp
buffer_pool<wf_buffer, 16> buffers;
// Creates pool with 2 wf_buffer objects initially
// Can grow to 16 buffers maximum
```
```

--------------------------------

### AudioReader Base Class init Method

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Pure virtual method for initializing the audio reader. Must connect to the audio backend and prepare audio capture.

```cpp
virtual bool init() = 0;
```

--------------------------------

### Using wf-recorder as a Virtual Camera (Raw Video)

Source: https://github.com/ammen99/wf-recorder/wiki/Home

Configure v4l2loopback and wf-recorder to use your desktop as a webcam. Adjust the device path (/dev/video2) if necessary. This uses raw video encoding.

```bash
sudo modprobe v4l2loopback exclusive_caps=1 card_label=WfRecorder
```

```bash
wf-recorder --muxer=v4l2 --codec=rawvideo --file=/dev/video2 -x yuv420p
```

--------------------------------

### Get Current Capture Buffer

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/buffer_pool.md

Returns the current buffer for writing newly captured frames. Thread-safe via internal mutex.

```cpp
auto& buffer = buffers.capture();
buffer.width = screen_width;
buffer.height = screen_height;
// Fill buffer with frame data

```

--------------------------------

### Get PipeWire Time Base

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Returns the PipeWire monotonic time (in microseconds) when the first audio buffer was received. Used for audio/video synchronization.

```cpp
uint64_t PipeWireReader::get_time_base() const override;
```

--------------------------------

### FrameWriter Constructor

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/FrameWriter.md

Initializes the FFmpeg context, sets up video and audio streams, configures hardware acceleration if needed, and applies filters. Throws/exits on initialization failure.

```APIDOC
## FrameWriter Constructor

### Description
Initializes the FFmpeg context, sets up video and audio streams, configures hardware acceleration if needed, and applies filters. Throws/exits on initialization failure.

### Method
Constructor

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **params** (const FrameWriterParams&) - Required - Configuration parameters for the frame writer including codec, output file, dimensions, and format

### Request Example
```cpp
std::atomic<bool> abort_flag{false};
FrameWriterParams params(abort_flag);
params.file = "output.mp4";
params.codec = "libx264";
params.width = 1920;
params.height = 1080;
params.stride = 1920 * 4;
params.format = INPUT_FORMAT_BGR0;
params.framerate = 60;
params.enable_audio = false;

FrameWriter writer(params);
```

### Response
None (Constructor)

#### Success Response
None

#### Response Example
None
```

--------------------------------

### List Available Outputs

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/README.md

Use the `-L` flag with `wf-recorder` to list available output devices or sources.

```bash
wf-recorder -L
```

--------------------------------

### Get Next Encoding Buffer

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/buffer_pool.md

Advances the encode index to the next buffer after encoding is complete. This marks the current buffer as unavailable for encoding and selects the next one.

```cpp
T& next_encode();
```

--------------------------------

### Get Current Encode Buffer

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/buffer_pool.md

Returns the current buffer ready for encoding. Thread-safe via internal mutex. This buffer typically contains previously captured data.

```cpp
while (buffers.encode().ready_encode()) {
    auto& buffer = buffers.encode();
    frame_writer->add_frame(buffer.data, buffer.timestamp, buffer.y_invert);
    buffers.next_encode();
}

```

--------------------------------

### Recording to Virtual Camera (v4l2 loopback)

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/configuration.md

Stream raw video output to a v4l2 loopback device, effectively creating a virtual camera.

```bash
wf-recorder --codec=rawvideo \
  --muxer=v4l2 \
  --file=/dev/video2
```

--------------------------------

### Enable Audio Recording

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Use the -a or --audio flag to enable audio recording. Optionally specify an audio device name.

```bash
wf-recorder --audio -f output.mkv           # Default device
wf-recorder -a my_audio_device              # Specific device
wf-recorder --audio=alsa_input.pci-0000_00_1f.3.analog-stereo
```

--------------------------------

### Get Audio Buffer Size

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/FrameWriter.md

Retrieves the required size in bytes for audio buffers passed to add_audio(). The size depends on configured sample rate and frame size.

```cpp
size_t audio_buf_size = writer.get_audio_buffer_size();
// Allocate buffer of this size for audio source
```

--------------------------------

### Get DRM Device Name from DMA-BUF Feedback

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/wayland-integration.md

Extracts the DRM device name from the DMA-BUF feedback provided by the compositor. This is crucial for enabling zero-copy transfers when the hardware device matches.

```cpp
static void dmabuf_feedback_main_device(void *, 
    struct zwp_linux_dmabuf_feedback_v1 *,
    struct wl_array *device) {
    
    // Extract device ID
    dev_t dev_id;
    memcpy(&dev_id, device->data, device->size);
    
    // Get DRM device node
    drmDevice *dev = NULL;
    drmGetDeviceFromDevId(dev_id, 0, &dev);
    
    // Determine device path
    if (dev->available_nodes & (1 << DRM_NODE_RENDER)) {
        drm_device_name = dev->nodes[DRM_NODE_RENDER];
    } else if (dev->available_nodes & (1 << DRM_NODE_PRIMARY)) {
        drm_device_name = dev->nodes[DRM_NODE_PRIMARY];
    }
    
    drmFreeDevice(&dev);
}
```

--------------------------------

### Display Version Information

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Show the wf-recorder version and build details, including git commit hash and branch if available.

```bash
wf-recorder --version
wf-recorder -v
```

--------------------------------

### List Available Displays

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Lists all available displays and exits. The output format shows the display number, name, and description.

```bash
wf-recorder --list-output
```

--------------------------------

### Recording with Audio

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/configuration.md

Record screen activity along with audio to an MKV file.

```bash
wf-recorder --audio -f video_with_sound.mkv
```

--------------------------------

### PipeWireReader::init

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Initializes the PipeWireReader by setting up the PipeWire thread loop, context, and core connection. This prepares the reader for subsequent audio capture operations.

```APIDOC
## PipeWireReader::init

### Description
Initializes PipeWire infrastructure: creates thread loop, context, and core connection. Does not yet connect to audio source (that happens in `start()`).

### Method
```cpp
bool PipeWireReader::init() override
```

### Parameters
None

### Request Example
```cpp
PipeWireReader* pw = new PipeWireReader();
pw->params.sample_rate = 48000;
pw->params.audio_frame_size = 2048;
pw->params.audio_source = "example_source_name";
if (pw->init()) {
    pw->start();
}
```

### Response
#### Success Response
* **bool** — `true` if PipeWire thread loop started successfully, `false` otherwise

#### Response Example
```cpp
// Returns true if PipeWire initialization is successful, false otherwise
```

### Errors
- Returns false if PipeWire library cannot be initialized
- Returns false if thread loop fails to start
- Logs errors to stderr
```

--------------------------------

### Wayland Global Registry Listener

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/wayland-integration.md

Handles discovered global Wayland interfaces by binding to them. This includes binding for wl_output, wl_shm, zwlr_screencopy_manager_v1, zxdg_output_manager_v1, and zwp_linux_dmabuf_v1. For linux-dmabuf, it also gets default feedback and adds a listener for it.

```cpp
void handle_global(void*, struct wl_registry *registry,
    uint32_t name, const char *interface, uint32_t version) {
    
    if (strcmp(interface, wl_output_interface.name) == 0) {
        // Bind wl_output
        auto output = (wl_output*)wl_registry_bind(registry, name, 
            &wl_output_interface, 4);
        wl_output_add_listener(output, &output_listener, ...);
    }
    else if (strcmp(interface, wl_shm_interface.name) == 0) {
        // Bind wl_shm (shared memory buffers)
        shm = (wl_shm*)wl_registry_bind(registry, name, 
            &wl_shm_interface, 1);
    }
    else if (strcmp(interface, zwlr_screencopy_manager_v1_interface.name) == 0) {
        // Bind screencopy manager
        screencopy_manager = (zwlr_screencopy_manager_v1*)
            wl_registry_bind(registry, name, 
            &zwlr_screencopy_manager_v1_interface, 3);
    }
    else if (strcmp(interface, zxdg_output_manager_v1_interface.name) == 0) {
        // Bind xdg-output manager
        xdg_output_manager = (zxdg_output_manager_v1*)
            wl_registry_bind(registry, name, 
            &zxdg_output_manager_v1_interface, 2);
    }
    else if (strcmp(interface, zwp_linux_dmabuf_v1_interface.name) == 0) {
        // Bind linux-dmabuf manager
        dmabuf = (zwp_linux_dmabuf_v1*)wl_registry_bind(registry, name, 
            &zwp_linux_dmabuf_v1_interface, 4);
        
        // Get feedback for device detection
        struct zwp_linux_dmabuf_feedback_v1 *feedback = 
            zwp_linux_dmabuf_v1_get_default_feedback(dmabuf);
        zwp_linux_dmabuf_feedback_v1_add_listener(feedback, 
            &dmabuf_feedback_listener, NULL);
    }
}
```

--------------------------------

### Basic Recording Commands

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Perform basic screen recordings using default settings, specifying a filename, or targeting a specific output monitor.

```bash
# Default output, variable framerate
wf-recorder

# Specified filename
wf-recorder -f my_recording.mkv

# Specific output monitor
wf-recorder -o HDMI-1 -f hdmi_recording.mkv
```

--------------------------------

### Monitor System Resources

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/README.md

Use `top` or `htop` to monitor CPU and memory usage during recording, especially when diagnosing performance issues.

```bash
top
```

```bash
htop
```

--------------------------------

### Basic Recording (H.264, 1080p, no audio)

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/configuration.md

Perform a basic screen recording to an MP4 file using default H.264 encoding.

```bash
wf-recorder -f recording.mp4
```

--------------------------------

### Configure Meson Build with Options

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/configuration.md

Use the -D flag with meson build to set configuration options. This is useful for specifying codecs, pixel formats, or audio backends during the build process.

```bash
meson build -Doption_name=value
```

```bash
meson build -Ddefault_codec=libx265 -Ddefault_pixel_format=hevc
```

```bash
meson build -Ddefault_audio_backend=pipewire -Dpulse=disabled
```

--------------------------------

### List Available Outputs

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Display a list of all available screen outputs that can be recorded.

```bash
wf-recorder -L
```

```bash
wf-recorder --list-output
```

--------------------------------

### Record with Custom Sample Rate and PipeWire Backend

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/configuration.md

Set a custom audio sample rate and specify the PipeWire audio backend.

```bash
# 44.1 kHz sample rate with PipeWire backend
wf-recorder --audio --audio-backend=pipewire -R 44100
```

--------------------------------

### Debugging and Help Commands

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Enable verbose FFmpeg output for debugging, list available output devices, or display the full help message with all available options.

```bash
# With FFmpeg verbose output
wf-recorder -l -f debug.mkv

# List available outputs
wf-recorder -L

# Help with all options
wf-recorder --help
```

--------------------------------

### List PulseAudio Devices

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/configuration.md

Use pactl to list available audio input devices for PulseAudio.

```bash
# List devices
pactl list sources | grep Name
```

--------------------------------

### Using wf-recorder as a Virtual Camera (Hardware Accelerated)

Source: https://github.com/ammen99/wf-recorder/wiki/Home

This command uses hardware acceleration (vaapi) for encoding to yuv420p pixel format when using wf-recorder as a virtual camera. This can be more efficient on certain GPUs.

```bash
wf-recorder -f /dev/video2 --muxer=v4l2 -d /dev/dri/renderD128 --codec=h264_vaapi --pixel-format=yuv420p
```

--------------------------------

### List PipeWire Audio Devices

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

List available PipeWire audio devices using pw-cli.

```bash
pw-cli list | grep -i audio
```

--------------------------------

### Record with Auto-Detected Audio Device

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/configuration.md

Enable audio recording and let wf-recorder automatically detect the audio device.

```bash
# Record with audio, auto-detect device
wf-recorder --audio
```

--------------------------------

### Record Screen with Audio

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Simultaneously record the screen and audio. The output file is specified with --file.

```bash
wf-recorder --audio --file=recording_with_audio.mp4
```

--------------------------------

### Read Man Page

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

View the manual page for wf-recorder.

```bash
man ./manpage/wf-recorder.1
```

--------------------------------

### Recording with Audio Input

Source: https://github.com/ammen99/wf-recorder/wiki/Home

Use the -a flag to enable audio recording. You may need to configure the audio input device using pavucontrol.

```bash
wf-recorder -a
```

--------------------------------

### List Available DRM Devices

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

List available DRM render devices to identify the correct path for the -d option.

```bash
ls -la /dev/dri/render*
```

--------------------------------

### Check PulseAudio Sources

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/README.md

Verify that PulseAudio is running and detecting audio input devices by listing available sources.

```bash
pactl list sources
```

--------------------------------

### Displaying Native Webcam Feed with GStreamer

Source: https://github.com/ammen99/wf-recorder/wiki/Home

This command uses gst-launch-1.0 to display a native webcam feed from /dev/video0 in a window.

```bash
gst-launch-1.0 v4l2src device=/dev/video0 ! videoconvert ! waylandsink
```

--------------------------------

### PulseReader::init

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Initializes the PulseReader by connecting to the PulseAudio daemon, preparing it for audio capture at the specified sample rate and buffer size. It also retrieves latency information for synchronization.

```APIDOC
## PulseReader::init

### Description
Establishes connection to PulseAudio daemon with stereo 32-bit float format at the specified sample rate. Retrieves latency information for audio/video synchronization.

### Method
```cpp
bool PulseReader::init() override
```

### Parameters
None

### Request Example
```cpp
PulseReader* pr = new PulseReader();
pr->params.sample_rate = 48000;
pr->params.audio_frame_size = 4096;
pr->params.audio_source = nullptr;
if (pr->init()) {
    pr->start();
} else {
    delete pr;
}
```

### Response
#### Success Response
* **bool** — `true` if initialization successful, `false` otherwise

#### Response Example
```cpp
// Returns true on successful connection to PulseAudio, false otherwise
```

### Errors
- Connection fails if PulseAudio daemon is not running or specified device doesn't exist
- Logs error message to stderr but does not throw exception
```

--------------------------------

### Buffer Pool Initialization and Usage in wf-recorder

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/buffer_pool.md

Shows the initialization of a `buffer_pool` for `wf_buffer` and its usage within the main capture and encode loops of the wf-recorder project. It includes waiting for buffers to be ready for capture or encoding.

```cpp
buffer_pool<wf_buffer, 16> buffers;

// In capture loop:
while (!exit_main_loop) {
    while (!buffers.capture().ready_capture()) {
        std::this_thread::sleep_for(std::chrono::microseconds(500));
    }
    // Use buffers.capture() to read into
    // When done: buffers.next_capture()
}

// In encode loop (separate thread):
while (!exit_main_loop) {
    while (!buffers.encode().ready_encode()) {
        std::this_thread::sleep_for(std::chrono::microseconds(1000));
    }
    frame_writer->add_frame(...);
    buffers.next_encode();
}
```

--------------------------------

### Set Audio Sample Format

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

Specify the audio sample format (bit depth). Use `s16` for standard 16-bit signed or `fltp` for 32-bit float planar.

```bash
wf-recorder --audio -X s16 -f output.mkv
wf-recorder -a --sample-format=fltp
```

```bash
wf-recorder -a -X s16 -f video.mkv
wf-recorder -a -X s32 -f audio.flac
```

--------------------------------

### Specify Output Filename

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Record the screen and save the output to a file with a specified name using the -f flag.

```bash
wf-recorder -f <filename>
```

--------------------------------

### List PipeWire Nodes

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/configuration.md

Use pw-cli to list available nodes for PipeWire.

```bash
# List devices
pw-cli list | grep node
```

--------------------------------

### High-Quality Recording with Custom Options

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/configuration.md

Configure advanced H.264 encoding options, including preset, CRF, and frame rate, for high-quality recordings.

```bash
wf-recorder -c libx264 \
  -p preset=slow \
  -p crf=18 \
  -r 60 \
  -f high_quality.mkv
```

--------------------------------

### Wayland Display Connection and Registry Initialization

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/wayland-integration.md

Connects to the Wayland display and obtains the registry to discover global Wayland objects. It then adds a listener to the registry and synchronizes to ensure all global objects are received.

```cpp
// Connect to Wayland display
display = wl_display_connect(NULL);

// Get registry to discover globals
struct wl_registry *registry = wl_display_get_registry(display);
wl_registry_add_listener(registry, &registry_listener, NULL);

// Sync to ensure all globals received
sync_wayland();
```

--------------------------------

### Initialize Buffer Pool

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/buffer_pool.md

Initializes the pool with 2 buffers pre-allocated. The pool can grow up to N buffers as needed.

```cpp
buffer_pool<wf_buffer, 16> buffers;
// Creates pool with 2 wf_buffer objects initially
// Can grow to 16 buffers maximum

```

--------------------------------

### AudioReader Factory Method create

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/api-reference/AudioReader.md

Static factory method that creates the appropriate audio reader implementation based on parameters. Tries PipeWire first, then PulseAudio.

```cpp
static AudioReader* create(AudioReaderParams params);
```

```cpp
AudioReaderParams params;
params.audio_backend = "pipewire";
params.sample_rate = 48000;
params.audio_frame_size = 1024;
params.audio_source = nullptr; // use default

AudioReader* reader = AudioReader::create(params);
if (reader) {
    reader->start();
}
```

--------------------------------

### Testing Virtual Camera Feed

Source: https://github.com/ammen99/wf-recorder/wiki/Home

Use ffplay to test the output of the virtual camera device created by wf-recorder and v4l2loopback.

```bash
ffplay /dev/video2
```

--------------------------------

### Specify Audio Codec

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Set the audio codec for recording using the -C or --audio-codec option.

```bash
wf-recorder -C <codec>
```

```bash
wf-recorder --audio-codec <codec>
```

--------------------------------

### Handle FFmpeg Initialization Errors

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/errors.md

Check the return value of FFmpeg functions like `av_hwdevice_ctx_create`. If an error occurs (non-zero return), log the human-readable error message using `averr` and handle the failure.

```cpp
int ret = av_hwdevice_ctx_create(&hw_ctx, ...);
if (ret != 0) {
    std::cerr << "Failed: " << averr(ret) << std::endl;
}
```

--------------------------------

### Output to v4l2 Loopback

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Configure wf-recorder to output to a v4l2 loopback device, using rawvideo codec and specifying the device file.

```bash
wf-recorder --muxer=v4l2 --codec=rawvideo --file=/dev/video2
```

--------------------------------

### Define Audio Capture Parameters

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/types.md

Use AudioReaderParams to configure audio capture settings like frame size, sample rate, source, and backend. Set audio_source to nullptr to use the default device.

```cpp
struct AudioReaderParams
{
    size_t audio_frame_size;
    uint32_t sample_rate;
    char *audio_source;
    std::string audio_backend;
};
```

```cpp
AudioReaderParams params;
params.audio_frame_size = 4096;
params.sample_rate = 48000;
params.audio_source = nullptr; // use default device
params.audio_backend = "pipewire";

AudioReader* reader = AudioReader::create(params);
```

--------------------------------

### List Available Audio Codecs

Source: https://github.com/ammen99/wf-recorder/blob/master/_autodocs/endpoints.md

List all available FFmpeg audio encoders to determine compatible codec names.

```bash
ffmpeg -hide_banner -encoders | grep -E '^ A'
```

--------------------------------

### Specify Audio Device

Source: https://github.com/ammen99/wf-recorder/blob/master/README.md

Record audio using a specific audio device. Use either the short -a or long --audio option.

```bash
wf-recorder -a<device>
```

```bash
wf-recorder --audio=<device>
```