# mrchahar/vlc architecture

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

- Interactive diagram: https://gitdiagram.com/mrchahar/vlc
- Repository: https://github.com/mrchahar/vlc

## Overview

#### Purpose and deliverables
VLC is a cross-platform native multimedia engine and player: it opens files, discs, devices, and network streams; decodes, filters, renders, converts, and retransmits media. It produces the `vlc` application, the embeddable LGPL `libVLC` API, and the underlying `libvlccore`.
- Entrypoints: `bin/vlc.c`, `src/libvlc.c`, `lib/core.c`
- Public embedding surface: `include/vlc/libvlc.h`, `include/vlc/libvlc_media_player.h`

#### Process bootstrap and core runtime
The executable parses startup configuration, initializes libVLC/core services, discovers modules, then creates interfaces and playback work. `libvlccore` owns shared object lifetime, configuration, threading, logging, networking, and module dispatch; higher layers consume its stable internal abstractions.
- Startup/build-time module composition: `bin/vlc.c`, `bin/vlc_static_modules.c`
- Core lifecycle: `src/libvlc.c`, `src/libvlc-module.c`
- Dynamic module registry/loading: `src/modules/modules.c`, `src/modules/cache.c`

#### Playback orchestration
The playlist selects media and drives the player. The player owns an input instance and coordinates state, timing, elementary-stream selection, audio output, video output, metadata, titles, and user-visible events. This is the main control boundary between UI/API commands and active playback.
- Playlist scheduling and requests: `src/playlist/playlist.c`, `src/playlist/player.c`
- Player state machine: `src/player/player.c`, `src/player/input.c`
- Input pipeline coordination: `src/input/input.c`, `src/input/decoder.c`, `src/input/es_out.c`

#### Media ingestion and decode pipeline
An input MRL is resolved through access modules (file, device, HTTP/RTP/SRT/etc.), optional stream filters/extractors, then a selected demuxer. Demuxers emit elementary streams; packetizers normalize framing; codec modules decode compressed audio/video/subtitles into core frames/pictures.
- Access and transport plugins: `modules/access/file.c`, `modules/access/http/access.c`, `modules/access/rtp/rtp.c`
- Container/adaptive demux: `modules/demux/mp4/mp4.c`, `modules/demux/mkv/demux.cpp`, `modules/demux/adaptive/adaptive.cpp`
- Decode boundary: `modules/packetizer/h264.c`, `modules/codec/avcodec/avcodec.c`, `include/vlc_decoder.h`

#### Rendering, filtering, and hardware boundaries
Decoded media travels through configurable audio/video/subpicture filter chains to OS- and GPU-specific outputs. Hardware acceleration is implemented as plugins, keeping Direct3D, VA-API, NVDEC, OpenGL, Vulkan, and platform windows outside the generic player/input core.
- Audio pipeline: `src/audio_output/output.c`, `src/audio_output/filters.c`, `modules/audio_output/`
- Video compositor/output core: `src/video_output/video_output.c`, `src/video_output/display.c`
- Hardware/platform implementations: `modules/hw/d3d11/d3d11_decoder.cpp`, `modules/hw/vaapi/decoder_device.c`, `modules/video_output/opengl/display.c`

#### Plugin-facing features and user control
Modules provide replaceable interfaces: Qt/QML, macOS, ncurses, CLI, DBus, Lua, HTTP control, discovery, metadata, and renderer support. GUIs and remote controls operate through player/playlist/core APIs rather than directly owning decoder pipelines.
- Primary desktop UI: `modules/gui/qt/qt.cpp`, `modules/gui/qt/maininterface/mainctx.cpp`
- Remote/control interfaces: `modules/control/dbus/dbus.c`, `modules/control/cli/cli.c`, `share/lua/intf/http.lua`
- Scripting and extensions runtime: `modules/lua/intf.c`, `share/lua/extensions/`

#### Output, conversion, and dependencies
The stream-output chain can transcode decoded streams, mux them, and send them to files or network protocols; HLS, RTP/RTSP, DLNA, Chromecast, and HTTP-oriented paths are represented as modules. External multimedia and platform libraries are curated as reproducible contrib builds. Core code is primarily C, with C++, Objective-C, assembly, and Rust components; builds support Autotools and Meson.
- Stream-output orchestration: `src/stream_output/stream_output.c`, `modules/stream_out/transcode/transcode.c`
- Mux/network sinks: `modules/mux/mp4/mp4.c`, `modules/access_output/http.c`, `modules/stream_out/hls/hls.c`
- Third-party dependency recipes: `contrib/src/main.mak`, `contrib/src/ffmpeg/rules.mak`, `contrib/src/qt/rules.mak`

Main entry points: [`modules/codec/avcodec/avcodec.c`](https://github.com/mrchahar/vlc/blob/master/modules/codec/avcodec/avcodec.c) (Packetize & decode), [`src/player/player.c`](https://github.com/mrchahar/vlc/blob/master/src/player/player.c) (Player state machine), [`src/input/input.c`](https://github.com/mrchahar/vlc/blob/master/src/input/input.c) (Input pipeline), [`src/libvlc.c`](https://github.com/mrchahar/vlc/blob/master/src/libvlc.c) (libVLC lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap & Core"]
  node_app["vlc application<br/>native executable<br/>[vlc.c]"]
  node_libvlc["libVLC lifecycle<br/>embedding API runtime<br/>[libvlc.c]"]
  node_public_api["Public libVLC API<br/>C headers<br/>[libvlc.h]"]
  node_core["libvlccore<br/>runtime services<br/>[core.c]"]
  node_module_registry["Module registry<br/>plugin loader<br/>[modules.c]"]
end

subgraph group_control["Control Plane"]
  node_playlist["Playlist scheduler<br/>playback requests<br/>[playlist.c]"]
  node_player["Player state machine<br/>playback orchestration<br/>[player.c]"]
end

subgraph group_ingest["Media Pipeline"]
  node_input["Input pipeline<br/>media coordinator<br/>[input.c]"]
  node_access["Access &amp; transport<br/>input plugins<br/>[access.c]"]
  node_demux["Demux &amp; adaptive<br/>container plugins<br/>[mp4.c]"]
  node_decode["Packetize &amp; decode<br/>codec plugins<br/>[avcodec.c]"]
end

subgraph group_render["Render &amp; Output"]
  node_audio["Audio output<br/>filter and sink pipeline<br/>[output.c]"]
  node_video["Video compositor<br/>display pipeline<br/>[video_output.c]"]
  node_stream_output["Stream output<br/>conversion orchestration<br/>[stream_output.c]"]
end

subgraph group_plugins["Plugin Ecosystem"]
  node_interfaces["UI &amp; controls<br/>interface modules<br/>[qt.cpp]"]
  node_hardware["Hardware &amp; GPU backends<br/>platform plugins<br/>[d3d11_decoder.cpp]"]
  node_mux_sinks["Mux &amp; network sinks<br/>output plugins<br/>[mp4.c]"]
  node_contrib["Contrib dependencies<br/>reproducible third-party builds<br/>[main.mak]"]
end

node_app -->|"initializes"| node_libvlc
node_public_api -->|"defines"| node_libvlc
node_libvlc -->|"starts"| node_core
node_core -->|"loads"| node_module_registry
node_module_registry -->|"activates"| node_interfaces
node_interfaces -->|"playback commands"| node_playlist
node_playlist -->|"selects media"| node_player
node_player -->|"owns"| node_input
node_input -->|"opens MRL"| node_access
node_access -->|"byte stream"| node_demux
node_demux -->|"elementary streams"| node_decode
node_decode -->|"audio frames"| node_audio
node_decode -->|"pictures and subtitles"| node_video
node_hardware -.->|"accelerates"| node_decode
node_hardware -.->|"platform display"| node_video
node_player -->|"controls output"| node_audio
node_player -->|"controls output"| node_video
node_input -->|"routes streams"| node_stream_output
node_stream_output -->|"transcode, mux, deliver"| node_mux_sinks
node_contrib -.->|"codec dependencies"| node_decode
node_contrib -.->|"UI dependencies"| node_interfaces

click node_app "https://github.com/mrchahar/vlc/blob/master/bin/vlc.c"
click node_libvlc "https://github.com/mrchahar/vlc/blob/master/src/libvlc.c"
click node_public_api "https://github.com/mrchahar/vlc/blob/master/include/vlc/libvlc.h"
click node_core "https://github.com/mrchahar/vlc/blob/master/lib/core.c"
click node_module_registry "https://github.com/mrchahar/vlc/blob/master/src/modules/modules.c"
click node_interfaces "https://github.com/mrchahar/vlc/blob/master/modules/gui/qt/qt.cpp"
click node_playlist "https://github.com/mrchahar/vlc/blob/master/src/playlist/playlist.c"
click node_player "https://github.com/mrchahar/vlc/blob/master/src/player/player.c"
click node_input "https://github.com/mrchahar/vlc/blob/master/src/input/input.c"
click node_access "https://github.com/mrchahar/vlc/blob/master/modules/access/http/access.c"
click node_demux "https://github.com/mrchahar/vlc/blob/master/modules/demux/mp4/mp4.c"
click node_decode "https://github.com/mrchahar/vlc/blob/master/modules/codec/avcodec/avcodec.c"
click node_audio "https://github.com/mrchahar/vlc/blob/master/src/audio_output/output.c"
click node_video "https://github.com/mrchahar/vlc/blob/master/src/video_output/video_output.c"
click node_hardware "https://github.com/mrchahar/vlc/blob/master/modules/hw/d3d11/d3d11_decoder.cpp"
click node_stream_output "https://github.com/mrchahar/vlc/blob/master/src/stream_output/stream_output.c"
click node_mux_sinks "https://github.com/mrchahar/vlc/blob/master/modules/mux/mp4/mp4.c"
click node_contrib "https://github.com/mrchahar/vlc/blob/master/contrib/src/main.mak"

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_app,node_libvlc,node_public_api,node_core,node_module_registry toneBlue
class node_playlist,node_player toneAmber
class node_input,node_access,node_demux,node_decode toneMint
class node_audio,node_video,node_stream_output toneRose
class node_interfaces,node_hardware,node_mux_sinks,node_contrib toneIndigo
```

## Components

### Bootstrap & Core

- [vlc application](https://github.com/mrchahar/vlc/blob/master/bin/vlc.c): native executable · `bin/vlc.c`
- [libVLC lifecycle](https://github.com/mrchahar/vlc/blob/master/src/libvlc.c): embedding API runtime · `src/libvlc.c`
- [Public libVLC API](https://github.com/mrchahar/vlc/blob/master/include/vlc/libvlc.h): C headers · Embedding and media-player surface. · `include/vlc/libvlc.h`
- [libvlccore](https://github.com/mrchahar/vlc/blob/master/lib/core.c): runtime services · Owns shared lifetime, configuration, threading, logging, and networking. · `lib/core.c`
- [Module registry](https://github.com/mrchahar/vlc/blob/master/src/modules/modules.c): plugin loader · Discovers and dispatches dynamic modules. · `src/modules/modules.c`

### Control Plane

- [Playlist scheduler](https://github.com/mrchahar/vlc/blob/master/src/playlist/playlist.c): playback requests · `src/playlist/playlist.c`
- [Player state machine](https://github.com/mrchahar/vlc/blob/master/src/player/player.c): playback orchestration · Coordinates input, timing, tracks, outputs, and events. · `src/player/player.c`

### Media Pipeline

- [Input pipeline](https://github.com/mrchahar/vlc/blob/master/src/input/input.c): media coordinator · `src/input/input.c`
- [Access & transport](https://github.com/mrchahar/vlc/blob/master/modules/access/http/access.c): input plugins · Opens files, devices, and network streams. · `modules/access/http/access.c`
- [Demux & adaptive](https://github.com/mrchahar/vlc/blob/master/modules/demux/mp4/mp4.c): container plugins · Resolves containers into elementary streams. · `modules/demux/mp4/mp4.c`
- [Packetize & decode](https://github.com/mrchahar/vlc/blob/master/modules/codec/avcodec/avcodec.c): codec plugins · Normalizes compressed streams and produces frames. · `modules/codec/avcodec/avcodec.c`

### Render & Output

- [Audio output](https://github.com/mrchahar/vlc/blob/master/src/audio_output/output.c): filter and sink pipeline · `src/audio_output/output.c`
- [Video compositor](https://github.com/mrchahar/vlc/blob/master/src/video_output/video_output.c): display pipeline · `src/video_output/video_output.c`
- [Stream output](https://github.com/mrchahar/vlc/blob/master/src/stream_output/stream_output.c): conversion orchestration · Builds transcoding, muxing, and delivery chains. · `src/stream_output/stream_output.c`

### Plugin Ecosystem

- [UI & controls](https://github.com/mrchahar/vlc/blob/master/modules/gui/qt/qt.cpp): interface modules · GUI and remote controls use core player APIs. · `modules/gui/qt/qt.cpp`
- [Hardware & GPU backends](https://github.com/mrchahar/vlc/blob/master/modules/hw/d3d11/d3d11_decoder.cpp): platform plugins · `modules/hw/d3d11/d3d11_decoder.cpp`
- [Mux & network sinks](https://github.com/mrchahar/vlc/blob/master/modules/mux/mp4/mp4.c): output plugins · `modules/mux/mp4/mp4.c`
- [Contrib dependencies](https://github.com/mrchahar/vlc/blob/master/contrib/src/main.mak): reproducible third-party builds · `contrib/src/main.mak`

## Connections

- vlc application → libVLC lifecycle: initializes
- Public libVLC API → libVLC lifecycle: defines
- libVLC lifecycle → libvlccore: starts
- libvlccore → Module registry: loads
- Module registry → UI & controls: activates
- UI & controls → Playlist scheduler: playback commands
- Playlist scheduler → Player state machine: selects media
- Player state machine → Input pipeline: owns
- Input pipeline → Access & transport: opens MRL
- Access & transport → Demux & adaptive: byte stream
- Demux & adaptive → Packetize & decode: elementary streams
- Packetize & decode → Audio output: audio frames
- Packetize & decode → Video compositor: pictures and subtitles
- Hardware & GPU backends → Packetize & decode: accelerates
- Hardware & GPU backends → Video compositor: platform display
- Player state machine → Audio output: controls output
- Player state machine → Video compositor: controls output
- Input pipeline → Stream output: routes streams
- Stream output → Mux & network sinks: transcode, mux, deliver
- Contrib dependencies → Packetize & decode: codec dependencies
- Contrib dependencies → UI & controls: UI dependencies