audiocapturemgr is a userspace daemon that captures live audio from the platform audio subsystem and exposes control and clip-ready notifications over the IARM inter-process communication bus. Audio payloads are delivered to clients via local IPC endpoints (for example UNIX domain sockets) rather than over IARM.

The service exposes audio capture sessions on a per-client basis. Each session is associated with the primary audio source and a delivery mode chosen at session open time: a buffered mode that maintains a rolling precapture queue and extracts audio clips on demand, or a realtime streaming mode that pushes live audio directly to the requesting client over a local socket connection. Clients are notified asynchronously over the bus when a requested audio clip becomes available.

Internally, a central capture manager owns the connection to the audio hardware, maintains data queues, and distributes incoming audio to all active client sessions. Each delivery mode is handled by a dedicated subsystem responsible for either managing the precapture buffer and scheduling clip extraction, or forwarding live audio buffers to a connected socket consumer.

```mermaid
flowchart LR

classDef Apps  stroke:#00B9F1,fill:#E6F7FD,stroke-width:2px;
classDef RDKMW stroke:#75D701,fill:#F1FFE6,stroke-width:2px;
classDef VL stroke:#808080,fill:#F2F2F2,stroke-width:2px;

subgraph Apps["Apps & Runtimes"]
    ClientApps["Client Applications"]
end

subgraph RDKMW["RDK Core Middleware"]
    IARMClients["IARM Clients"]
    ACM["audiocapturemgr\n(standalone daemon)"]
    IARM["IARM Bus"]
end

subgraph VL["Vendor Layer"]
    RMF["RMF AudioCapture HAL\n(media-utils)"]
end

ClientApps -->|Firebolt APS| IARMClients
IARMClients --> IARM
IARM --> ACM
ACM -->|API Calls| RMF
RMF -->|Service Interaction| ACM
ACM -->|Event Notification| IARM
```

Key Features & Responsibilities:

• IARM service endpoint for audio capture control: Exposes session lifecycle operations (open, close, start, stop, sample request) and audio/output property management as callable methods on the IARM bus, allowing any authorized process to control audio capture without direct hardware access.
• Session-based output routing: Directs captured audio to either buffered clip extraction or realtime local socket streaming depending on the delivery mode selected when a session is opened.
• Audio capture queue management: Maintains incoming and outgoing data queues between the hardware capture callback and active client sessions, with background monitoring to detect and log periods where audio inflow stalls.
• Clip request scheduling: Satisfies audio clip requests either immediately from the precaptured rolling buffer or after a configured fresh-capture window, then notifies the requesting client asynchronously over the bus when the clip is ready.
• Audio format conversion: Supports passthrough, channel downmix, sample-rate downsample, and combined conversion paths to adapt captured audio to the format required by each client session.

Design

The component is organized around a single capture source manager (q_mgr) with a client registration model. Audio data arrives via the RMF capture callback (q_mgr::data_callback) registered in q_mgr::start() (via RMF_AudioCapture_Start() settings) and is enqueued as audio_buffer objects with reference counting. A dedicated data_processor_thread swaps incoming and outgoing queues under mutex protection and dispatches buffer pointers to all registered clients, while update_buffer_references() adjusts refcounts based on active clients. A data_monitor thread runs independently to detect and log periods where inflow byte count stops advancing. Session orchestration in acm_session_mgr separates control-plane concerns (IARM method dispatch, session lookup, result mapping) from data-plane processing (capture, queuing, conversion, output transport). Queue overflow is bounded by MAX_QMGR_BUFFER_DURATION_S = 30 seconds, beyond which the incoming queue is flushed.

Northbound interaction flows exclusively through IARM, where clients invoke named calls and receive result codes and events. Southbound interaction uses the RMF AudioCapture APIs currently exercised by this component — Open, GetDefaultSettings, Start, Stop, and Close (primary source only).

IPC mechanisms include IARM call registration and event broadcast for control and asynchronous notifications, UNIX domain sockets (AF_UNIX, SOCK_STREAM) for realtime PCM streaming (ip_out_client) and socket-delivery clip output (music_id_client/socket_adaptor), and internal control pipes combined with select() loops to shut down listener threads in ip_out_client.

Buffered clip output (opened with BUFFERED_FILE_OUTPUT) is currently delivered over a UNIX domain socket (the session API constructs music_id_client in SOCKET_OUTPUT mode, and dataLocator is the socket path). File-mode delivery via std::ofstream exists in music_id_client but is not wired into the session manager.

```mermaid
graph LR

subgraph Proc["audiocapturemgr process (C++)"]
    direction TB
    subgraph Control["Control Plane"]
        Main["acm_main\nmain / launcher"]
        SessionMgr["acm_session_mgr\nIARM method handlers\nsession list management"]
    end
    subgraph Capture["Capture & Queuing"]
        QMgr["q_mgr\nRMF capture device\nqueue manager / client fan-out"]
        Buf["audio_buffer\nrefcounted PCM buffer"]
    end
    subgraph Delivery["Output Delivery"]
        MID["music_id_client\nrolling precapture queue\nclip extraction worker"]
        IPO["ip_out_client\nrealtime UNIX socket writer\nlistener thread"]
        Conv["audio_converter\ndownmix / downsample\nsink abstraction"]
        Sock["socket_adaptor\nUNIX socket listener\nconnected-callback dispatch"]
    end
end

subgraph External["External Systems"]
    direction TB
    IARMBus[("IARM Bus")]
    RMFHAL[("RMF AudioCapture HAL\n(media-utils)")]
    UDSClients[("UNIX Domain\nSocket Clients")]
end

Main --> SessionMgr
SessionMgr -->|Event Notification| IARMBus
IARMBus --> SessionMgr
SessionMgr --> MID
SessionMgr --> IPO
QMgr --> RMFHAL
RMFHAL -->|Service Interaction| QMgr
QMgr --> Buf
MID --> QMgr
MID --> Conv
MID --> Sock
IPO --> QMgr
IPO --> UDSClients
Sock --> UDSClients
```

Threading Model

• Threading Architecture: Multi-threaded, event-driven around RMF capture callbacks and semaphore/worker loops.
• Main Thread: Process startup, IARM activate/deactivate, and blocked wait via pause().
• Worker Threads:
• q_mgr processing thread (pthread_create): waits on sem_t m_sem and wakes on notify_data_ready() to swap queues and dispatch buffers to clients.
• q_mgr data monitor thread (std::thread): checks m_inflow_byte_counter every 5 seconds via std::condition_variable and logs stall and resume events.
• music_id_client worker thread (std::thread): decrements time_remaining on pending requests and calls grab_last_n_seconds() to fulfill them.
• ip_out_client listener thread (pthread_create): runs select() over the listen socket and a control pipe, accepts connections, and stores the write fd.
• socket_adaptor listener thread (std::thread): accepts one connection and invokes the callback registered via register_data_ready_callback().
• Synchronization: pthread_mutex_t (session manager, queue, client list), std::mutex (data monitor), sem_t (queue wakeup), and a global audio-buffer mutex for refcount operations.
• Async / Event Dispatch: RMF capture callback pushes data into the incoming queue and posts the semaphore. IARM BroadcastEvent delivers AUDIO_CLIP_READY to subscribed clients. Socket callbacks trigger clip delivery for socket-output mode.

Prerequisites and Dependencies

Platform and Integration Requirements

• Build Dependencies: Build-time recipe dependencies: virtual/vendor-media-utils (RMF AudioCapture provider), media-utils-headers (supplies rmfAudioCapture.h), iarmbus, iarmmgrs, libunpriv, safec-common-wrapper, and safec (conditional on safec in DISTRO_FEATURES); runtime dependency on virtual/vendor-media-utils; link flags: -lprivilege, and conditionally pkg-config --libs libsafec when safec is in DISTRO_FEATURES; compile flags: -DDROP_ROOT_PRIV (enables privilege-drop path at build time), conditionally pkg-config --cflags libsafec or -fPIC, and -DSAFEC_DUMMY_API when safec is absent from DISTRO_FEATURES.
• HAL: RMF AudioCapture HAL (rmfAudioCapture.h). See Major HAL APIs Integration for the full API surface and return values.
• IARM Bus: Bus name audiocapturemgr; method names defined in include/audiocapturemgr_iarm.h.
• Systemd Services: iarmbusd.service must be running before audiocapturemgr starts.
• Startup Order: Defined by systemd unit After= / Requires= dependency on iarmbusd.service.

Component State Flow

Initialization to Active State

```mermaid
sequenceDiagram
    participant System as systemd
    participant Comp as audiocapturemgr
    participant IARM as IARM Bus
    participant Q as q_mgr
    participant RMF as RMF AudioCapture

    System->>Comp: ExecStart /usr/bin/audiocapturemgr
    Comp->>IARM: IARM_Bus_Init("audiocapturemgr")
    Comp->>IARM: IARM_Bus_Connect()
    Comp->>IARM: IARM_Bus_RegisterEvent(IARMBUS_MAX_ACM_EVENT)
    Comp->>IARM: IARM_Bus_RegisterCall(open, close, start, stop, requestSample, ...)
    Note over Comp: Control plane active — IARM methods available

    IARM->>Comp: open(source=0, output_type)
    Comp->>Comp: create session + create client (music_id or ip_out) bound to existing q_mgr
    Note over Comp,Q: q_mgr performs RMF Open + GetDefaultSettings during acm_session_mgr initialization

    IARM->>Comp: start(session_id)
    Comp->>Q: register_client + start()
    Q->>RMF: Start capture with settings and data callback
    RMF-->>Q: audio data via callback

    Q-->>Comp: clip ready (callback)
    Comp->>IARM: BroadcastEvent DATA_CAPTURE_IARM_EVENT_AUDIO_CLIP_READY

    System->>Comp: terminate (signal)
    Comp->>IARM: IARM_Bus_Disconnect + Term
```

Runtime State Changes

State Change Triggers (all via IARM calls):

• open creates a session and binds the output-mode client implementation; the output type cannot change without closing and reopening the session.
• start registers the client to q_mgr and initiates audio capture; data flow begins.
• stop unregisters the client and halts audio capture, data flow stops.
• close destroys the session object and releases resources.
• setAudioProperties may trigger a capture restart after applying new properties to q_mgr.

Context Switching Scenarios:

• Output mode switch (buffered vs. realtime) requires close/open because the client type is fixed at open_handler() time.
• If a write error occurs on the realtime socket in ip_out_client::data_callback, the write fd is closed and m_num_connections is decremented.
• When the incoming queue exceeds MAX_QMGR_BUFFER_DURATION_S seconds of buffered data, the incoming queue is flushed to discard queued buffers (see q_mgr::add_data()).

Call Flows

Initialization Call Flow

```mermaid
sequenceDiagram
    participant Main as acm_main
    participant Mgr as acm_session_mgr
    participant IARM as IARM Bus

    Main->>Mgr: get_instance()->activate()
    Mgr->>IARM: IARM_Bus_Init("audiocapturemgr")
    Mgr->>IARM: IARM_Bus_Connect()
    Mgr->>IARM: IARM_Bus_RegisterEvent(IARMBUS_MAX_ACM_EVENT)
    Mgr->>IARM: IARM_Bus_RegisterCall(requestSample)
    Mgr->>IARM: IARM_Bus_RegisterCall(open)
    Mgr->>IARM: IARM_Bus_RegisterCall(close)
    Mgr->>IARM: IARM_Bus_RegisterCall(start)
    Mgr->>IARM: IARM_Bus_RegisterCall(stop)
    Mgr->>IARM: IARM_Bus_RegisterCall(getDefaultAudioProperties)
    Mgr->>IARM: IARM_Bus_RegisterCall(getAudioProperties)
    Mgr->>IARM: IARM_Bus_RegisterCall(getOutputProperties)
    Mgr->>IARM: IARM_Bus_RegisterCall(setAudioProperties)
    Mgr->>IARM: IARM_Bus_RegisterCall(setOutputProperties)
    Main->>Main: pause()
```

Request Processing Call Flow

```mermaid
%%{init: { 'sequence': { 'actorMargin': 80, 'width': 200, 'messageMargin': 50, 'noteMargin': 25, 'mirrorActors': true, 'messageFontSize': 24, 'noteFontSize': 22, 'actorFontSize': 22 } } }%%
sequenceDiagram
    participant Client as IARM Client
    participant IARM as IARM Bus
    participant Mgr as acm_session_mgr
    participant MID as music_id_client
    participant Q as q_mgr

    Client->>IARM: IARM_Bus_Call(requestSample, {duration, is_precapture})
    IARM->>Mgr: get_sample_handler()

    Note over Client,Q: Branch on is_precapture flag

    alt is_precapture == true
        Note over Mgr,Q: Precapture path — serve from rolling buffer
        Mgr->>MID: grab_precaptured_sample(filename)
        MID->>Q: use buffered audio_buffer queue
        MID-->>Mgr: result (immediate)

    else is_precapture == false
        Note over Mgr,MID: Fresh capture path — defer until audio is collected
        Mgr->>MID: grab_fresh_sample(seconds, filename, callback)
        Note over MID: worker thread decrements timer, fulfills on completion
        MID-->>Mgr: async via request_callback
    end

    Note over Mgr,Client: Common path — notify client with clip location
    Mgr->>IARM: IARM_Bus_BroadcastEvent(DATA_CAPTURE_IARM_EVENT_AUDIO_CLIP_READY,{dataLocator})
    IARM-->>Client: event payload with dataLocator
```

Internal Modules

Component Interactions

Interaction Matrix

Events Published

IPC Flow Patterns

Primary Request / Response Flow:

```mermaid
sequenceDiagram
    participant Client as Client Application
    participant IARM as IARM Bus
    participant ACM as audiocapturemgr
    participant RMF as RMF AudioCapture

    Client->>IARM: IARM_Bus_Call("audiocapturemgr", method, payload)
    IARM->>ACM: Dispatch to registered handler
    ACM->>RMF: Start, stop, or configure capture as needed
    RMF-->>ACM: Status or callback data
    ACM-->>IARM: Result code written into payload struct
    IARM-->>Client: Call return with populated payload
```

Event Notification Flow:

```mermaid
sequenceDiagram
    participant Client as IARM Client
    participant ACM as audiocapturemgr
    participant IARM as IARM Bus

    Client->>IARM: IARM_Bus_Call(requestSample, {duration, is_precapture})
    IARM->>ACM: Dispatch to registered handler
    ACM->>ACM: generate clip (immediate or deferred)
    ACM->>IARM: IARM_Bus_BroadcastEvent(DATA_CAPTURE_IARM_EVENT_AUDIO_CLIP_READY)
    IARM-->>Client: event payload {dataLocator}
```

Implementation Details

Major HAL APIs Integration

Key Implementation Logic

• State / Lifecycle Management:
• Process lifecycle (activate / pause / deactivate) is implemented in src/acm_main.cpp and src/acm_session_mgr.cpp.

• Per-session state (enable flag, session lookup by ID, create/destroy) is managed in src/acm_session_mgr.cpp using the acm_session_t struct.

• Event Processing:

• q_mgr::data_callback (called from RMF capture thread) creates an audio_buffer and calls add_data() which enqueues it and posts m_sem.
• q_mgr::data_processor_thread wakes on the semaphore, locks m_q_mutex, swaps queues, calls update_buffer_references() to set refcounts per registered client count, and invokes data_callback() on each client.

• Clip-ready notifications flow through request_callback → IARM_Bus_BroadcastEvent(DATA_CAPTURE_IARM_EVENT_AUDIO_CLIP_READY).

• Error Handling Strategy:

• Invalid session IDs return ACM_RESULT_BAD_SESSION_ID.
• Unsupported API paths return ACM_RESULT_UNSUPPORTED_API.
• Duration values outside allowed range return ACM_RESULT_DURATION_OUT_OF_BOUNDS.
• Precapture-specific failure codes: ACM_RESULT_PRECAPTURE_DURATION_TOO_LONG (254) and ACM_RESULT_PRECAPTURE_NOT_SUPPORTED (255).
• Generic failures return ACM_RESULT_GENERAL_FAILURE.

• Write failures on the realtime socket cause the connection to be closed and the write fd reset to -1.

• Logging & Diagnostics:

• Source files use INFO, WARN, ERROR, and DEBUG macros throughout.
• q_mgr::data_monitor logs data stall and resume events with a 5-second polling interval.
• Queue flush events and incomplete writes are logged at WARN level.

Configuration

Key Configuration Parameters

Runtime Configuration

Runtime behavior is changed via IARM calls.

# Open a session (source=0, output_type=BUFFERED_FILE_OUTPUT or REALTIME_SOCKET)
IARM_Bus_Call("audiocapturemgr", "open", iarmbus_open_args)

# Change audio capture properties for an open session
IARM_Bus_Call("audiocapturemgr", "setAudioProperties", iarmbus_acm_arg_t)

# Change output delivery properties (e.g., precapture buffer duration)
IARM_Bus_Call("audiocapturemgr", "setOutputProperties", iarmbus_acm_arg_t)

Configuration Persistence

Configuration changes are not persisted across reboots.