# canardoux/flutter_sound architecture

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

- Interactive diagram: https://gitdiagram.com/canardoux/flutter_sound
- Repository: https://github.com/canardoux/flutter_sound

## Overview

##### Project Type and Purpose
- This is a cross-platform Flutter plugin (“library package”) called Flutter Sound. Its purpose is to expose audio playback and recording capabilities to Flutter apps on iOS, Android, Web (and desktop via examples). It provides:
- A Dart API layer (playback, recording, utilities)
- Native implementations on Android (Java), iOS (Objective-C/Swift)
- A web shim (Javascript via tau_web.js)

##### File Structure Analysis
- Top-level directories:
- lib/           ← Dart API & public interfaces
- android/       ← Android plugin code (Java, Gradle)
- ios/           ← iOS plugin code (Objective-C/Swift, CocoaPods)
- assets/js/     ← Web support scripts (tau_web.js, async_processor.js)
- example/       ← Demo Flutter app showcasing plugin usage (multi-platform)
- doc/api/       ← Generated API documentation
- Key config/build files: pubspec.yaml, android/build.gradle, ios/flutter_sound.podspec
- Patterns: Flutter plugin pattern using MethodChannel for mobile, JS interop for web.

##### README Highlights
- Purpose: play/record audio from buffers, files, streams, remote URLs
- Platforms: iOS ≥10, Android API 21+, Web (Chrome/Firefox/Safari)
- Core features: codec support, live streams, resource management

a. Main Components
- Flutter App (UI)
- Flutter Sound Dart Package
– Public API layer (lib/public/*.dart)
– Core logic (lib/src/tau.dart)
- Platform Channel Layer
– MethodChannel (mobile)
– JS Interop (web)
- Native Modules
– Android: FlutterSoundManager, PlayerManager, RecorderManager, session, etc.
– iOS: FlutterSoundManager, FlutterSoundPlayerManager, FlutterSoundRecorderManager
– Web: async_processor.js, tau_web.js
- OS Audio Services
– Android AudioTrack/MediaRecorder APIs
– iOS AVFoundation
– Browser Web Audio API

b. Interactions
- Flutter App calls public Dart API → invokes MethodChannel.invokeMethod()
- MethodChannel marshals requests → native code on Android/iOS
- Native module executes audio operations → returns results/events via MethodChannel
- Dart side propagates events to Flutter UI (playback state, progress, errors)
- On Web: Dart API calls JS functions in async_processor.js / tau_web.js → Browser Web Audio

c. Architectural Patterns
- Plugin architecture using platform channels (MethodChannel & EventChannel)
- Layered separation: UI ←→ Dart API ←→ Platform channel ←→ Native implementation
- Modular managers for player/recorder sessions
- Streams support: audio data flows as Dart Streams to/from native layers

d. Key Technologies
- Flutter/Dart (Flutter plugin framework)
- Android: Java, Gradle, Android SDK Audio APIs
- iOS: Objective-C/Swift, CocoaPods, AVFoundation
- Web: JavaScript, W3C Web Audio API (via tau_web.js)
- API docs via dartdoc

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Flutter UI Layer
    subgraph "Flutter Application" 
        direction TB
        App["Flutter UI"]:::frontend
        Example["Example App"]:::frontend
    end

    %% Dart API Layer
    subgraph "Dart API Layer" 
        direction TB
        PluginEntry["flutter_sound.dart"]:::dart
        PublicPlayer["flutter_sound_player.dart"]:::dart
        PublicRecorder["flutter_sound_recorder.dart"]:::dart
        PublicHelper["flutter_sound_helper.dart"]:::dart
        CoreLogic["tau.dart"]:::dart
    end

    %% Platform Channel Layer
    subgraph "Platform Channel Layer"
        direction TB
        MethodChannel["MethodChannel"]:::channel
        JSInterop["JS Interop"]:::channel
    end

    %% Native Modules
    subgraph "Native Modules"
        direction TB
        subgraph "Android Module"
            direction TB
            AndroidRegistrar["FlutterSound.java"]:::native
            AndroidSession["FlutterSoundSession.java"]:::native
            AndroidPlayerMgr["FlutterSoundPlayerManager.java\n& FlutterSoundPlayer.java"]:::native
            AndroidRecorderMgr["FlutterSoundRecorderManager.java\n& FlutterSoundRecorder.java"]:::native
            AndroidBuild["build.gradle"]:::anc
        end
        subgraph "iOS Module"
            direction TB
            iOSInterface["FlutterSound.h\n& FlutterSound.mm"]:::native
            iOSSession["FlutterSoundManager.h\n& FlutterSoundManager.m"]:::native
            iOSPlayerMgr["FlutterSoundPlayerManager.h\n& FlutterSoundPlayerManager.mm"]:::native
            iOSRecorderMgr["FlutterSoundRecorderManager.h\n& FlutterSoundRecorderManager.mm"]:::native
            iOSBuild["flutter_sound.podspec"]:::anc
        end
        subgraph "Web JS Layer"
            direction TB
            AsyncProc["async_processor.js"]:::web
            TauWeb["tau_web.js"]:::web
        end
    end

    %% OS Audio Services
    subgraph "OS Audio Services"
        direction TB
        AndroidOS["Android AudioTrack/\nMediaRecorder APIs"]:::os
        iOSOS["iOS AVFoundation"]:::os
        BrowserOS["Web Audio API"]:::os
    end

    %% Ancillary
    Docs["API Documentation"]:::anc
    Config["pubspec.yaml\nanalysis_options.yaml"]:::anc

    %% Connections: UI to Dart API
    App -->|"uses plugin"| PluginEntry
    Example -->|"demo uses plugin"| PluginEntry

    %% Dart API internal
    PluginEntry --> PublicPlayer
    PluginEntry --> PublicRecorder
    PluginEntry --> PublicHelper
    PublicPlayer --> CoreLogic
    PublicRecorder --> CoreLogic
    PublicHelper --> CoreLogic

    %% Dart API to Platform Channels
    CoreLogic -->|"invokeMethod"| MethodChannel
    CoreLogic -->|"js interop call"| JSInterop

    %% Platform Channels to Native
    MethodChannel --> AndroidRegistrar
    MethodChannel --> iOSInterface
    JSInterop --> AsyncProc
    JSInterop --> TauWeb

    %% Native to OS services
    AndroidRegistrar --> AndroidSession
    AndroidSession --> AndroidPlayerMgr
    AndroidSession --> AndroidRecorderMgr
    AndroidPlayerMgr --> AndroidOS
    AndroidRecorderMgr --> AndroidOS

    iOSInterface --> iOSSession
    iOSSession --> iOSPlayerMgr
    iOSSession --> iOSRecorderMgr
    iOSPlayerMgr --> iOSOS
    iOSRecorderMgr --> iOSOS

    AsyncProc --> BrowserOS
    TauWeb --> BrowserOS

    %% Events back to Dart
    AndroidOS -.->|"events/callbacks"| MethodChannel
    iOSOS -.->|"events/callbacks"| MethodChannel
    BrowserOS -.->|"stream events"| JSInterop
    MethodChannel -.->|"onProgress/onComplete"| CoreLogic
    JSInterop -.->|"onProgress/onComplete"| CoreLogic
    CoreLogic -.->|"updates"| App

    %% Ancillary connections
    Config --- PluginEntry
    Config --- AndroidBuild
    Config --- iOSBuild
    Docs -.-> PublicPlayer
    Docs -.-> PublicRecorder
    Docs -.-> PublicHelper
    Docs -.-> CoreLogic

    %% Click events
    click PublicPlayer "https://github.com/canardoux/flutter_sound/blob/master/lib/public/flutter_sound_player.dart"
    click PublicRecorder "https://github.com/canardoux/flutter_sound/blob/master/lib/public/flutter_sound_recorder.dart"
    click PublicHelper "https://github.com/canardoux/flutter_sound/blob/master/lib/public/flutter_sound_helper.dart"
    click CoreLogic "https://github.com/canardoux/flutter_sound/blob/master/lib/src/tau.dart"
    click PluginEntry "https://github.com/canardoux/flutter_sound/blob/master/lib/flutter_sound.dart"
    click AndroidRegistrar "https://github.com/canardoux/flutter_sound/blob/master/android/src/main/java/xyz/canardoux/fluttersound/FlutterSound.java"
    click AndroidSession "https://github.com/canardoux/flutter_sound/blob/master/android/src/main/java/xyz/canardoux/fluttersound/FlutterSoundSession.java"
    click AndroidPlayerMgr "https://github.com/canardoux/flutter_sound/blob/master/android/src/main/java/xyz/canardoux/fluttersound/FlutterSoundPlayerManager.java"
    click AndroidPlayerMgr "https://github.com/canardoux/flutter_sound/blob/master/android/src/main/java/xyz/canardoux/fluttersound/FlutterSoundPlayer.java"
    click AndroidRecorderMgr "https://github.com/canardoux/flutter_sound/blob/master/android/src/main/java/xyz/canardoux/fluttersound/FlutterSoundRecorderManager.java"
    click AndroidRecorderMgr "https://github.com/canardoux/flutter_sound/blob/master/android/src/main/java/xyz/canardoux/fluttersound/FlutterSoundRecorder.java"
    click AndroidBuild "https://github.com/canardoux/flutter_sound/blob/master/android/build.gradle"
    click iOSInterface "https://github.com/canardoux/flutter_sound/blob/master/ios/Classes/FlutterSound.h"
    click iOSInterface "https://github.com/canardoux/flutter_sound/blob/master/ios/Classes/FlutterSound.mm"
    click iOSSession "https://github.com/canardoux/flutter_sound/blob/master/ios/Classes/FlutterSoundManager.h"
    click iOSSession "https://github.com/canardoux/flutter_sound/blob/master/ios/Classes/FlutterSoundManager.m"
    click iOSPlayerMgr "https://github.com/canardoux/flutter_sound/blob/master/ios/Classes/FlutterSoundPlayerManager.h"
    click iOSPlayerMgr "https://github.com/canardoux/flutter_sound/blob/master/ios/Classes/FlutterSoundPlayerManager.mm"
    click iOSRecorderMgr "https://github.com/canardoux/flutter_sound/blob/master/ios/Classes/FlutterSoundRecorderManager.h"
    click iOSRecorderMgr "https://github.com/canardoux/flutter_sound/blob/master/ios/Classes/FlutterSoundRecorderManager.mm"
    click iOSBuild "https://github.com/canardoux/flutter_sound/blob/master/ios/flutter_sound.podspec"
    click AsyncProc "https://github.com/canardoux/flutter_sound/blob/master/assets/js/async_processor.js"
    click TauWeb "https://github.com/canardoux/flutter_sound/blob/master/assets/js/tau_web.js"
    click Example "https://github.com/canardoux/flutter_sound/blob/master/example/lib/main.dart"
    click Docs "https://github.com/canardoux/flutter_sound/tree/master/doc/api/"
    click Config "https://github.com/canardoux/flutter_sound/blob/master/pubspec.yaml"

    %% Styles
    classDef frontend fill:#89CFF0,stroke:#036,stroke-width:1px
    classDef dart fill:#C3FDB8,stroke:#060,stroke-width:1px
    classDef channel fill:#FFEB3B,stroke:#995500,stroke-width:1px
    classDef native fill:#FFAB91,stroke:#C63F17,stroke-width:1px
    classDef web fill:#D1C4E9,stroke:#673AB7,stroke-width:1px
    classDef os fill:#E0E0E0,stroke:#555,stroke-width:1px
    classDef anc fill:#F5F5F5,stroke:#888,stroke-width:1px
```
