# kartik-venugopal/swift-ffmpeg-player architecture

> Architecture diagram of the GitHub repository kartik-venugopal/swift-ffmpeg-player, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kartik-venugopal/swift-ffmpeg-player
- Repository: https://github.com/kartik-venugopal/swift-ffmpeg-player

## Overview

FFmpeg Player is a macOS audio-player demo: the user opens a file, its audio is demuxed and decoded, PCM is resampled and buffered, and AVAudioEngine schedules it for playback. The app also displays metadata and cover art and supports seeking; packet-table duration and seek indexing cover files without usable duration data. The graph follows the documented product stages and sampled call/data evidence; some UI-to-player wiring and unsampled subsystem details are omitted where source excerpts do not establish the exact links.

Main entry points: [`Sources/FFmpeg/Utils/FFmpegDecoder.swift`](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Utils/FFmpegDecoder.swift) (Frame decoder), [`Sources/FFmpeg/Wrappers/FFmpegFormatContext.swift`](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegFormatContext.swift) (Format context), [`Sources/Player/Player.swift`](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/Player/Player.swift) (Playback scheduler), [`Sources/FFmpeg/Wrappers/AudioFileContext.swift`](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/AudioFileContext.swift) (Audio file context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App interface"]
  node_ui["Player controls"]
  node_app["App lifecycle<br/>[AppDelegate.swift]"]
  node_metaui["Metadata display"]
end

subgraph group_media["Media access"]
  node_format["Format context"]
  node_audiofile["Audio file context"]
  node_stream["Audio stream"]
  node_image["Cover art stream"]
  node_packet["Packet reading<br/>[FFmpegPacket.swift]"]
  node_packettable["Packet seek table"]
end

subgraph group_decode["Decode and convert"]
  node_decoder["Frame decoder"]
  node_codec["Audio codec"]
  node_frame["Decoded frames<br/>[FFmpegFrame.swift]"]
  node_resampler["PCM resampler"]
  node_pcm["PCM buffers"]
end

subgraph group_playback["Audio playback"]
  node_player["Playback scheduler<br/>[Player.swift]"]
  node_scheduling["Buffer scheduling"]
  node_engine["Audio engine<br/>[AudioEngine.swift]"]
end

subgraph group_metadata["Track information"]
  node_metadata["Metadata reader"]
  node_trackinfo["Track information<br/>[TrackInfo.swift]"]
end

node_user(("Listener"))
node_hardware(("Audio output"))

node_user -->|"opens and controls"| node_ui
node_ui -->|"controls playback"| node_player
node_player -->|"opens file"| node_audiofile
node_audiofile -->|"creates context"| node_format
node_format -->|"selects stream"| node_stream
node_format -->|"selects cover art"| node_image
node_decoder -->|"reads packets"| node_packet
node_packet -->|"reads from"| node_format
node_decoder -->|"decodes packets"| node_codec
node_codec -->|"produces frames"| node_frame
node_decoder -->|"queues frames"| node_frame
node_decoder -->|"converts samples"| node_resampler
node_decoder -->|"builds buffers"| node_pcm
node_player -->|"requests frames"| node_decoder
node_player -->|"schedules audio"| node_scheduling
node_scheduling -->|"enqueues buffers"| node_engine
node_engine -->|"renders audio"| node_hardware
node_format -->|"builds seek index"| node_packettable
node_player -->|"seeks stream"| node_audiofile
node_format -->|"reads tags"| node_metadata
node_audiofile -->|"provides track data"| node_trackinfo
node_ui -->|"displays metadata"| node_metaui
node_metaui -->|"shows track details"| node_user

click node_ui "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/UI/PlayerViewController.swift"
click node_app "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/AppDelegate.swift"
click node_format "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegFormatContext.swift"
click node_audiofile "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/AudioFileContext.swift"
click node_stream "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegAudioStream.swift"
click node_image "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegImageStream.swift"
click node_packet "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegPacket.swift"
click node_packettable "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Utils/FFmpegPacketTable.swift"
click node_decoder "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Utils/FFmpegDecoder.swift"
click node_codec "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegAudioCodec.swift"
click node_frame "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegFrame.swift"
click node_resampler "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegResamplingContext.swift"
click node_pcm "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Utils/FFmpegDecoder%2BPCMBuffer.swift"
click node_player "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/Player/Player.swift"
click node_scheduling "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/Player/PlayerScheduling.swift"
click node_engine "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/Player/AudioEngine.swift"
click node_metadata "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Utils/FFmpegMetadataReader.swift"
click node_trackinfo "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/Metadata/TrackInfo.swift"
click node_metaui "https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/UI/PlayerViewController.swift"

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_ui,node_app,node_metaui toneBlue
class node_format,node_audiofile,node_stream,node_image,node_packet,node_packettable toneAmber
class node_decoder,node_codec,node_frame,node_resampler,node_pcm toneMint
class node_player,node_scheduling,node_engine toneRose
class node_metadata,node_trackinfo,node_user,node_hardware toneIndigo
```

## Components

### App interface

- [Player controls](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/UI/PlayerViewController.swift): `Sources/UI/PlayerViewController.swift`
- [App lifecycle](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/AppDelegate.swift): `Sources/AppDelegate.swift`
- [Metadata display](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/UI/PlayerViewController.swift): `Sources/UI/PlayerViewController.swift`

### Media access

- [Format context](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegFormatContext.swift): `Sources/FFmpeg/Wrappers/FFmpegFormatContext.swift`
- [Audio file context](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/AudioFileContext.swift): `Sources/FFmpeg/Wrappers/AudioFileContext.swift`
- [Audio stream](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegAudioStream.swift): `Sources/FFmpeg/Wrappers/FFmpegAudioStream.swift`
- [Cover art stream](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegImageStream.swift): `Sources/FFmpeg/Wrappers/FFmpegImageStream.swift`
- [Packet reading](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegPacket.swift): `Sources/FFmpeg/Wrappers/FFmpegPacket.swift`
- [Packet seek table](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Utils/FFmpegPacketTable.swift): `Sources/FFmpeg/Utils/FFmpegPacketTable.swift`

### Decode and convert

- [Frame decoder](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Utils/FFmpegDecoder.swift): `Sources/FFmpeg/Utils/FFmpegDecoder.swift`
- [Audio codec](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegAudioCodec.swift): `Sources/FFmpeg/Wrappers/FFmpegAudioCodec.swift`
- [Decoded frames](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegFrame.swift): `Sources/FFmpeg/Wrappers/FFmpegFrame.swift`
- [PCM resampler](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Wrappers/FFmpegResamplingContext.swift): `Sources/FFmpeg/Wrappers/FFmpegResamplingContext.swift`
- [PCM buffers](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Utils/FFmpegDecoder%2BPCMBuffer.swift): `Sources/FFmpeg/Utils/FFmpegDecoder+PCMBuffer.swift`

### Audio playback

- [Playback scheduler](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/Player/Player.swift): `Sources/Player/Player.swift`
- [Buffer scheduling](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/Player/PlayerScheduling.swift): `Sources/Player/PlayerScheduling.swift`
- [Audio engine](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/Player/AudioEngine.swift): `Sources/Player/AudioEngine.swift`

### Track information

- [Metadata reader](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/FFmpeg/Utils/FFmpegMetadataReader.swift): `Sources/FFmpeg/Utils/FFmpegMetadataReader.swift`
- [Track information](https://github.com/kartik-venugopal/swift-ffmpeg-player/blob/master/Sources/Metadata/TrackInfo.swift): `Sources/Metadata/TrackInfo.swift`

### Other components

- **Listener**
- **Audio output**

## Connections

- Listener → Player controls: opens and controls
- Player controls → Playback scheduler: controls playback
- Playback scheduler → Audio file context: opens file
- Audio file context → Format context: creates context
- Format context → Audio stream: selects stream
- Format context → Cover art stream: selects cover art
- Frame decoder → Packet reading: reads packets
- Packet reading → Format context: reads from
- Frame decoder → Audio codec: decodes packets
- Audio codec → Decoded frames: produces frames
- Frame decoder → Decoded frames: queues frames
- Frame decoder → PCM resampler: converts samples
- Frame decoder → PCM buffers: builds buffers
- Playback scheduler → Frame decoder: requests frames
- Playback scheduler → Buffer scheduling: schedules audio
- Buffer scheduling → Audio engine: enqueues buffers
- Audio engine → Audio output: renders audio
- Format context → Packet seek table: builds seek index
- Playback scheduler → Audio file context: seeks stream
- Format context → Metadata reader: reads tags
- Audio file context → Track information: provides track data
- Player controls → Metadata display: displays metadata
- Metadata display → Listener: shows track details