# ensaryusuf/just_audio architecture

> Architecture diagram of the GitHub repository ensaryusuf/just_audio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ensaryusuf/just_audio
- Repository: https://github.com/ensaryusuf/just_audio

## Overview

##### Project type and purpose
- This is a Flutter “plugin” package whose sole responsibility is to play audio on Android, iOS, macOS, Windows, Linux and Web.
- It exposes a Dart API (`lib/just_audio.dart`) that forwards playback commands and receives playback events via Flutter’s platform channels.
- Platform‐specific native code implements the actual audio playback (ExoPlayer on Android, AVFoundation on Apple, libwinmedia on Windows/Linux, HTML5 Audio on Web).

##### File structure
- **lib/**
- just_audio.dart: Dart API surface, defines `AudioPlayer`, `AudioSource` classes.
- **android/src/main/java/...**
- JustAudioPlugin.java, AudioPlayer.java, BetterEventChannel.java, MainMethodCallHandler.java → plugin registration, MethodChannel handlers, ExoPlayer wrapper.
- **ios/Classes**, **darwin/Classes**, **macos/Classes**
- Objective-C plugin code: JustAudioPlugin.m, AudioPlayer.m, AudioSource variants → AVAudioEngine/AVPlayer wrappers.
- **example/**
- A Flutter app showing how to call into `AudioPlayer` and integrate example audio files.
- **test/**
- Dart unit tests for the Dart layer.

##### README for architectural insights
- Relies on two Flutter channel types:
- MethodChannel: synchronous commands (play, pause, setUrl, etc.)
- EventChannel: asynchronous event streams (player state, position, buffering).
- Uses composition of `AudioSource` types (ConcatenatingAudioSource, ClippingAudioSource, LoopingAudioSource) on both Dart and native sides.
- Maintains two orthogonal states: `playing` and `processingState`.

##### Main components & interactions
a. **Dart layer (Flutter app code)**
- UI Widgets call into → `AudioPlayer` API (lib/just_audio.dart)
b. **Plugin bridge (Flutter engine)**
- MethodChannel “just_audio_method_call” → routes commands to native registrations
- EventChannel “just_audio_event_stream” → streams events back to Dart
c. **Platform‐specific implementations**
– Android: ExoPlayer wrapper classes receive MethodChannel calls, post events via BetterEventChannel
– iOS/macOS: AVPlayer/AVAudioEngine wrapper classes in Objective-C
– Windows/Linux: libwinmedia C/C++ library invoked through method calls
– Web: HTML5 Audio API through platform‐channel stubs generated by flutter_web_plugins
d. **External systems**
- Network / File System / Asset Bundle → URI or file sources
- Operating System audio session (ducking, interruptions)

##### Architectural patterns & principles
- **Single Responsibility Principle**: plugin “just” plays audio; other concerns (background, session management) are in separate plugins.
- **Adapter pattern**: Dart API adapts to different native audio engines per platform.
- **Strategy/composition**: `AudioSource` types composed into playlists, loops, clip segments.
- **Reactive streams**: state and position exposed via EventChannel as Rx-style streams.
- **Platform abstraction via method/event channels**: cleanly separates Dart from platform code.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Dart Layer
    subgraph "Dart Layer"
        direction TB
        UI["UI / Flutter App"]:::dart
        DartAPI["just_audio Dart API\n(AudioPlayer, AudioSource)"]:::dart
    end

    %% Platform Channels Layer
    subgraph "Platform Channels"
        direction TB
        MethodCh["MethodChannel\n\"just_audio_method_call\""]:::channel
        EventCh["EventChannel\n\"just_audio_event_stream\""]:::channel
    end

    %% Native Layer
    subgraph "Native Layer"
        direction TB

        subgraph "Android (ExoPlayer)" 
            direction TB
            AndroidReg["Android Plugin Registration\n(JustAudioPlugin.java)"]:::android
            AndroidHandler["Android MethodCall Handler\n(MainMethodCallHandler.java)"]:::android
            AndroidAudioPlayer["Android ExoPlayer Wrapper\n(AudioPlayer.java)"]:::android
            AndroidEvent["Android EventChannel Adapter\n(BetterEventChannel.java)"]:::android
        end

        subgraph "iOS/macOS (AVPlayer/AVAudioEngine)"
            direction TB
            iOSReg["iOS Plugin Registration\n(JustAudioPlugin.m)"]:::ios
            iOSAudioPlayer["iOS AudioPlayer Wrapper\n(AudioPlayer.m)"]:::ios
            iOSEvent["iOS EventChannel Adapter\n(BetterEventChannel.m)"]:::ios
            iOSSources["iOS AudioSource Implementations"]:::ios
            macOSReg["macOS Plugin Registration\n(JustAudioPlugin.m)"]:::ios
            macOSAudioPlayer["macOS AudioPlayer Wrapper\n(AudioPlayer.m)"]:::ios
            macOSEvent["macOS EventChannel Adapter\n(BetterEventChannel.m)"]:::ios
            macOSSources["macOS AudioSource Implementations"]:::ios
        end

        subgraph "Windows/Linux (libwinmedia)"
            direction TB
            WinPlugin["Windows/Linux Plugin\n(libwinmedia)"]:::win
        end

        subgraph "Web (HTML5 Audio)"
            direction TB
            WebPlugin["Web Plugin\n(HTML5 Audio)"]:::web
        end
    end

    %% External Resources
    ExternalSys["Network / File System / Asset"]:::external

    %% Connections
    UI -->|"calls"| DartAPI
    DartAPI -->|"play(), pause(), setUrl()"| MethodCh
    MethodCh -->|"route commands"| AndroidReg
    MethodCh -->|"route commands"| iOSReg
    MethodCh -->|"route commands"| WinPlugin
    MethodCh -->|"route commands"| WebPlugin

    AndroidReg --> AndroidHandler
    AndroidHandler -->|"invoke"| AndroidAudioPlayer
    AndroidAudioPlayer -->|"audio frames"| EventCh
    AndroidAudioPlayer -->|"load from"| ExternalSys
    EventCh -->|"playerStateStream"| DartAPI

    iOSReg --> iOSAudioPlayer
    iOSAudioPlayer -->|"audio frames"| EventCh
    iOSAudioPlayer -->|"load from"| ExternalSys
    iOSEvent -->|"playerStateStream"| DartAPI
    iOSSources --> iOSAudioPlayer

    macOSReg --> macOSAudioPlayer
    macOSAudioPlayer -->|"audio frames"| EventCh
    macOSAudioPlayer -->|"load from"| ExternalSys
    macOSEvent -->|"playerStateStream"| DartAPI
    macOSSources --> macOSAudioPlayer

    WinPlugin -->|"audio frames"| EventCh
    WinPlugin -->|"load from"| ExternalSys
    EventCh -->|"playerStateStream"| DartAPI

    WebPlugin -->|"audio frames"| EventCh
    WebPlugin -->|"load from"| ExternalSys
    EventCh -->|"playerStateStream"| DartAPI

    %% Click Events
    click DartAPI "https://github.com/ensaryusuf/just_audio/blob/master/lib/just_audio.dart"
    click UI "https://github.com/ensaryusuf/just_audio/blob/master/example/lib/main.dart"
    click AndroidReg "https://github.com/ensaryusuf/just_audio/blob/master/android/src/main/java/com/ryanheise/just_audio/JustAudioPlugin.java"
    click AndroidHandler "https://github.com/ensaryusuf/just_audio/blob/master/android/src/main/java/com/ryanheise/just_audio/MainMethodCallHandler.java"
    click AndroidAudioPlayer "https://github.com/ensaryusuf/just_audio/blob/master/android/src/main/java/com/ryanheise/just_audio/AudioPlayer.java"
    click AndroidEvent "https://github.com/ensaryusuf/just_audio/blob/master/android/src/main/java/com/ryanheise/just_audio/BetterEventChannel.java"
    click iOSReg "https://github.com/ensaryusuf/just_audio/blob/master/ios/Classes/JustAudioPlugin.m"
    click iOSAudioPlayer "https://github.com/ensaryusuf/just_audio/blob/master/ios/Classes/AudioPlayer.m"
    click iOSEvent "https://github.com/ensaryusuf/just_audio/blob/master/ios/Classes/BetterEventChannel.m"
    click iOSSources "https://github.com/ensaryusuf/just_audio/tree/master/ios/Classes"
    click macOSReg "https://github.com/ensaryusuf/just_audio/blob/master/macos/Classes/JustAudioPlugin.m"
    click macOSAudioPlayer "https://github.com/ensaryusuf/just_audio/blob/master/macos/Classes/AudioPlayer.m"
    click macOSEvent "https://github.com/ensaryusuf/just_audio/blob/master/macos/Classes/BetterEventChannel.m"
    click macOSSources "https://github.com/ensaryusuf/just_audio/tree/master/macos/Classes"

    %% Styles
    classDef dart fill:#e0f7fa,stroke:#0288d1,color:#000;
    classDef channel fill:#eceff1,stroke:#90a4ae,color:#000;
    classDef android fill:#c8e6c9,stroke:#2e7d32,color:#000;
    classDef ios fill:#b2dfdb,stroke:#00695c,color:#000;
    classDef win fill:#ffe0b2,stroke:#ef6c00,color:#000;
    classDef web fill:#e1bee7,stroke:#8e24aa,color:#000;
    classDef external fill:#fff3e0,stroke:#ff6f00,color:#000;
```
