# rdkcentral/rialto architecture

> Architecture diagram of the GitHub repository rdkcentral/rialto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rdkcentral/rialto
- Repository: https://github.com/rdkcentral/rialto
- Video tour (about a minute): https://gitdiagram.com/rdkcentral/rialto/video

## Overview

1. This repository is a C++ media playback stack split into a client side, a server side, and a server-manager/control-plane. The main product is not a generic app framework; it is a session-based media pipeline with DRM/EME support and a separate WebAudio path.

2. The highest-level runtime boundary is:
   - client libraries used by an application,
   - a media server process that performs playback/DRM work,
   - a serverManager process that starts, monitors, and controls session-server instances.

3. The client side lives under `media/client`. It exposes the public media APIs in `media/public` and implements them with local controller objects plus IPC proxies. The main client entry points are `Control`, `MediaKeys`, `MediaPipeline`, `MediaPipelineCapabilities`, and `WebAudioPlayer`.

4. Client calls are translated into protobuf-based IPC requests by `media/client/ipc`. This layer is organized by module: Control, MediaKeys, MediaPipeline, MediaKeysCapabilities, MediaPipelineCapabilities, and WebAudioPlayer. It also owns the client-side connection abstraction and the transport module glue.

5. The IPC substrate is shared across the repo in `ipc/`. It uses protobuf schemas plus named-socket transport, with client/server controller and channel abstractions. This is the main boundary between processes, and it is the point where requests, callbacks, and module routing are defined.

6. Media sample transport is split from control traffic. Media frames and metadata are carried through shared memory and versioned frame readers/writers (`MediaFrameWriterV1/V2`, `DataReaderV1/V2`, `SharedMemoryBuffer`, `SharedMemoryHandle`). That means control stays on IPC, while encoded media data moves through shared memory for throughput.

7. The media server core is under `media/server/main`. It owns session state and orchestration objects such as `MainThread`, `ActiveRequests`, `HeartbeatProcedure`, `NeedMediaData`, `MediaKeySession`, `MediaPipelineServerInternal`, and `WebAudioPlayerServerInternal`. This is where request handling turns into actual playback/session state transitions.

8. Actual playback is implemented in `media/server/gstplayer`. This is the GStreamer-backed engine, with separate implementations for generic media playback and WebAudio playback. The task-based design is important: playback operations like play/pause/flush/seek/attach-source/render-frame are modeled as discrete tasks and executed on worker/dispatcher threads.

9. DRM/EME is a first-class subsystem. The server-side `MediaKeys` and `MediaKeysCapabilities` path integrates with OpenCDM via the wrappers in `wrappers/` and the stubs under `stubs/opencdm`. The data flow is: client EME requests -> IPC module service -> server `MediaKeySession`/keys logic -> OpenCDM-backed decrypt/session operations.

10. WebAudio is a parallel pipeline rather than a special case of the main media path. It has its own client IPC, server IPC service, and GStreamer player implementation. That separation matters for diagramming because WebAudio has its own buffering, caps, volume, play/pause, and buffer-write flow.

11. `media/server/ipc` is the server-side counterpart to the client IPC layer. It adapts incoming module messages into internal services such as Control, MediaPipeline, MediaKeys, MediaKeysCapabilities, WebAudioPlayer, and the server-manager integration modules. It also contains the session-management and application-management servers.

12. `serverManager/` is the control plane. It includes a public service API, service implementation, IPC controller, config reader, healthcheck logic, and a simulator/test service. Its job is to manage session-server applications, read config, observe state, and expose lifecycle/health controls.

13. `common/`, `logging/`, and `wrappers/` form the shared foundation:
   - `common` provides threading, timer, profiling, and Linux helpers,
   - `logging` centralizes runtime log configuration,
   - `wrappers` isolate external dependencies such as Glib, GStreamer, JSONCPP, Linux APIs, Thunder, RDK GStreamer Utils, and OpenCDM.
   These are important architectural boundaries because they keep platform/vendor APIs out of the core domain logic.

14. The repo is heavily test-driven. `tests/` contains unit tests and component tests for client, server, IPC, serverManager, wrappers, and shared media utilities. The GitHub Actions workflows also show CI gates for formatting, linting, protobuf compatibility, valgrind, and component/system-style tests.

15. Build and packaging are CMake-centric, with helper scripts for native builds, unit tests, and Yocto-oriented workflows. The architecture is therefore both process-oriented and dependency-isolated: generated protobuf IPC at the boundaries, shared-memory for bulk media data, and wrapper layers for all external runtime dependencies.

Main entry points: [`media/server/main`](https://github.com/rdkcentral/rialto/tree/master/media/server/main) (Session core), [`media/server/ipc`](https://github.com/rdkcentral/rialto/tree/master/media/server/ipc) (Server IPC), [`media/client/main`](https://github.com/rdkcentral/rialto/tree/master/media/client/main) (Client core), [`serverManager/service`](https://github.com/rdkcentral/rialto/tree/master/serverManager/service) (Manager service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client side"]
  node_media_public["Public API<br/>headers"]
  node_media_client_main["Client core<br/>client runtime"]
  node_media_client_ipc["Client IPC<br/>client transport"]
end

subgraph group_server["Media server"]
  node_media_server_ipc["Server IPC<br/>module service"]
  node_media_server_main["Session core<br/>session runtime"]
  node_media_server_gstplayer["GStreamer engine<br/>playback engine"]
  node_media_server_service["Session service<br/>session server"]
end

subgraph group_control["Control plane"]
  node_server_manager_service["Manager service<br/>control service"]
  node_server_manager_ipc["Manager IPC<br/>control ipc"]
  node_server_manager_common["Manager core<br/>health/config"]
end

subgraph group_foundation["Shared foundation"]
  node_media_common["Frame utils<br/>shm framing"]
  node_ipc_common["IPC substrate<br/>ipc transport"]
  node_common["Common utils<br/>threading/timing"]
  node_logging["Logging"]
  node_wrappers["Wrappers<br/>external adapters"]
end

node_media_public -->|"API contracts"| node_media_client_main
node_media_client_main -->|"requests"| node_media_client_ipc
node_media_client_ipc -->|"transport"| node_ipc_common
node_ipc_common -->|"deliver"| node_media_server_ipc
node_media_server_ipc -->|"dispatch"| node_media_server_main
node_media_server_main -->|"playback"| node_media_server_gstplayer
node_media_server_main -->|"shm frames"| node_media_common
node_media_client_main -->|"write frames"| node_media_common
node_media_server_main -->|"deps"| node_wrappers
node_media_server_gstplayer -->|"gstreamer"| node_wrappers
node_media_server_ipc -->|"cdm"| node_wrappers
node_media_client_main -->|"web audio"| node_media_server_ipc
node_media_server_ipc -->|"manager ctrl"| node_server_manager_ipc
node_server_manager_ipc -->|"control"| node_server_manager_service
node_server_manager_service -->|"manage"| node_server_manager_common
node_server_manager_service -->|"ipc loop"| node_ipc_common
node_media_server_service -->|"serve"| node_media_server_ipc
node_media_server_service -->|"runtime"| node_media_server_main
node_media_client_main -.->|"client logs"| node_logging
node_media_server_main -.->|"server logs"| node_logging
node_server_manager_service -.->|"manager logs"| node_logging
node_common -.->|"helpers"| node_media_server_main
node_common -.->|"helpers"| node_ipc_common
node_common -.->|"helpers"| node_server_manager_common

click node_media_public "https://github.com/rdkcentral/rialto/tree/master/media/public"
click node_media_client_main "https://github.com/rdkcentral/rialto/tree/master/media/client/main"
click node_media_client_ipc "https://github.com/rdkcentral/rialto/tree/master/media/client/ipc"
click node_media_common "https://github.com/rdkcentral/rialto/tree/master/media/common"
click node_ipc_common "https://github.com/rdkcentral/rialto/tree/master/ipc"
click node_media_server_ipc "https://github.com/rdkcentral/rialto/tree/master/media/server/ipc"
click node_media_server_main "https://github.com/rdkcentral/rialto/tree/master/media/server/main"
click node_media_server_gstplayer "https://github.com/rdkcentral/rialto/tree/master/media/server/gstplayer"
click node_media_server_service "https://github.com/rdkcentral/rialto/tree/master/media/server/service"
click node_server_manager_service "https://github.com/rdkcentral/rialto/tree/master/serverManager/service"
click node_server_manager_ipc "https://github.com/rdkcentral/rialto/tree/master/serverManager/ipc"
click node_server_manager_common "https://github.com/rdkcentral/rialto/tree/master/serverManager/common"
click node_common "https://github.com/rdkcentral/rialto/tree/master/common"
click node_logging "https://github.com/rdkcentral/rialto/tree/master/logging"
click node_wrappers "https://github.com/rdkcentral/rialto/tree/master/wrappers"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_media_public,node_media_client_main,node_media_client_ipc toneBlue
class node_media_server_ipc,node_media_server_main,node_media_server_gstplayer,node_media_server_service toneAmber
class node_server_manager_service,node_server_manager_ipc,node_server_manager_common toneMint
class node_media_common,node_ipc_common,node_common,node_logging,node_wrappers toneRose
```

## Components

### Client side

Application-facing media APIs and their IPC adapters.

- [Public API](https://github.com/rdkcentral/rialto/tree/master/media/public): headers · Application-facing media interfaces and common API contracts. · `media/public`
- [Client core](https://github.com/rdkcentral/rialto/tree/master/media/client/main): client runtime · Local controllers and public API implementations for control, playback, DRM, and WebAudio. · `media/client/main`
- [Client IPC](https://github.com/rdkcentral/rialto/tree/master/media/client/ipc): client transport · Client-side protobuf IPC modules and connection glue. · `media/client/ipc`

### Media server

Session runtime, IPC services, playback engine, DRM, and shared-memory data handling.

- [Server IPC](https://github.com/rdkcentral/rialto/tree/master/media/server/ipc): module service · Server-side module services and client adapters for control, playback, DRM, WebAudio, and server-manager integration. · `media/server/ipc`
- [Session core](https://github.com/rdkcentral/rialto/tree/master/media/server/main): session runtime · Main-thread orchestration, active requests, heartbeat, shared-memory readers, and session state. · `media/server/main`
- [GStreamer engine](https://github.com/rdkcentral/rialto/tree/master/media/server/gstplayer): playback engine · GStreamer-backed generic media and WebAudio playback implementation with task-based execution. · `media/server/gstplayer`
- [Session service](https://github.com/rdkcentral/rialto/tree/master/media/server/service): session server · Session-server application services and entrypoint used by the session-server process. · `media/server/service`

### Control plane

serverManager process that manages session-server applications and health/state.

- [Manager service](https://github.com/rdkcentral/rialto/tree/master/serverManager/service): control service · Config-driven service layer for managing session-server applications and lifecycle state. · `serverManager/service`
- [Manager IPC](https://github.com/rdkcentral/rialto/tree/master/serverManager/ipc): control ipc · Control-plane IPC loop, controller, and server-manager module handling. · `serverManager/ipc`
- [Manager core](https://github.com/rdkcentral/rialto/tree/master/serverManager/common): health/config · App manager, healthcheck, utilities, and simulator/test support for server-manager state. · `serverManager/common`

### Shared foundation

Cross-cutting IPC substrate, common utilities, logging, and external wrappers.

- [Frame utils](https://github.com/rdkcentral/rialto/tree/master/media/common): shm framing · Versioned media frame writers and schema helpers for shared-memory sample transport. · `media/common`
- [IPC substrate](https://github.com/rdkcentral/rialto/tree/master/ipc): ipc transport · Shared named-socket transport, channels, controllers, and protobuf-based process boundary. · `ipc`
- [Common utils](https://github.com/rdkcentral/rialto/tree/master/common): threading/timing · Shared threading, timer, profiling, and Linux helpers. · `common`
- [Logging](https://github.com/rdkcentral/rialto/tree/master/logging): runtime logging · Centralized log configuration and file/env handling. · `logging`
- [Wrappers](https://github.com/rdkcentral/rialto/tree/master/wrappers): external adapters · Isolation layer for Glib, GStreamer, JSONCPP, Linux, Thunder, RDK utilities, and OpenCDM. · `wrappers`

## Connections

- Public API → Client core: API contracts · Public interfaces are implemented by client-side controllers and proxies.
- Client core → Client IPC: requests · Client entry points translate into IPC module calls.
- Client IPC → IPC substrate: transport · Client IPC uses the shared IPC substrate and protobuf channels.
- IPC substrate → Server IPC: deliver · Named-socket IPC delivers requests to server-side module services.
- Server IPC → Session core: dispatch · Module services adapt incoming messages into session and playback internals.
- Session core → GStreamer engine: playback · Session orchestration drives GStreamer-based playback engines.
- Session core → Frame utils: shm frames · Session runtime consumes versioned shared-memory media data.
- Client core → Frame utils: write frames · Client-side media paths prepare shared-memory frame data for transport.
- Session core → Wrappers: deps · Server internals use wrappers around external runtime dependencies.
- GStreamer engine → Wrappers: gstreamer · Playback engine is implemented on top of wrapped GStreamer and related vendor APIs.
- Server IPC → Wrappers: cdm · DRM/session flows depend on OpenCDM and related wrappers.
- Client core → Server IPC: web audio · WebAudio and media control requests are routed through server IPC.
- Server IPC → Manager IPC: manager ctrl · Server-side IPC includes integration modules for the manager control plane.
- Manager IPC → Manager service: control · Manager IPC drives the public service implementation.
- Manager service → Manager core: manage · Service layer relies on app management and healthcheck core.
- Manager service → IPC substrate: ipc loop · Manager service uses the shared IPC substrate for control messages.
- Session service → Server IPC: serve · Session-server application services expose the media server over IPC.
- Session service → Session core: runtime · The service entrypoint boots the session runtime and playback orchestration.
- Client core → Logging: client logs · Client components feed centralized log configuration.
- Session core → Logging: server logs · Server components use centralized logging.
- Manager service → Logging: manager logs · Control-plane service uses centralized logging.
- Common utils → Session core: helpers · Common threading and timing helpers support session orchestration.
- Common utils → IPC substrate: helpers · IPC utilities reuse shared threading and Linux helpers.
- Common utils → Manager core: helpers · Manager utilities build on shared common primitives.
