# doublesymmetry/react-native-track-player architecture

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

- Interactive diagram: https://gitdiagram.com/doublesymmetry/react-native-track-player
- Repository: https://github.com/doublesymmetry/react-native-track-player

## Overview

##### Main Components
- Native Playback Modules:
- Android: Look in the android directory for Java/Kotlin source files, service implementations (e.g., MusicService.kt), and Android-specific resources (AndroidManifest.xml, proguard files).
- iOS: Check the ios directories and RNTrackPlayer project files which include Objective-C/Swift source files, bridging headers, and platform-specific models such as Capabilities.swift, MetadataAdapter.swift, and RNTrackPlayerBridge.m.
- Windows: See the windows directory with C++ source files and project files (vcxproj, sln) that provide native playback functionalities.
- Web: Located in the web folder, providing Player, PlaylistPlayer, and error handling modules (e.g., SetupNotCalledError.ts).
- JavaScript/TypeScript Layer:
- The src directory contains the core React Native module (TrackPlayerModule.ts, constants, hooks, interfaces) that acts as a wrapper exposing public APIs and managing state, events, and communication between the React Native app and the underlying native modules.
- Hooks and event interfaces facilitate integration with React’s component model, handling playback state updates and managing events.
- Examples & Documentation:
- The example folder contains sample projects demonstrating integration with React Native. These examples show configurations for Android, iOS, and even Windows, as well as usage of the JS APIs.
- The docs directory (with its extensive versioned documentation) outlines API details, guides, and usage instructions.
- Build and Configuration:
- Configuration files (.eslintrc.js, .prettierrc.js, Husky hooks, and package.json) exist at the root to ensure code quality as well as consistent builds across environments.
- Project-level files like react-native-track-player.podspec and the various Gradle build scripts indicate how the native build systems are integrated with the JavaScript layer.

##### Relationships and Interactions
- That the Example projects leverage the JS API (“TrackPlayerModule”) to initialize and control the playback, providing a clear usage flow from user interfaces through application logic into the native playback services.
- An “External Integration” or “Media Control Interfaces” component that handles external events such as Bluetooth controls, lock screen updates, or smartwatch integrations.

##### Important Architectural Patterns
- Modularization: The project follows a modular design where each platform has its own native implementation conforming to a common JS API interface.
- Bridge Pattern: Utilization of the React Native Bridge to abstract native functionalities for JavaScript consumption.
- Separation of Concerns: Clear division between presentation (Example UI components), business logic (JS hooks and state management), and native playback services.
- Event-Driven Architecture: Playback events (e.g., playing, pausing, error events) and lifecycle events are routed via event emitters (see hooks and interface definitions) to facilitate communication across layers.

##### Technologies, Frameworks, and Libraries
- For Native Code: Android (Java/Kotlin, Android Services), iOS (Objective-C/Swift, AVFoundation), Windows (C++/WinRT).
- For JS/TS: React Native, TypeScript, React Hooks, and interfaces for strongly typed events and state.
- Build/Tooling: Gradle (Android), Xcode (iOS projects), and npm/yarn for JavaScript dependency management.
- Documentation: Tools like Docusaurus (docs directory) to build and host API docs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Native Platforms"
        A1["Android Playback Service"]:::native
        I1["iOS Playback Service"]:::native
        W1["Windows Playback Module"]:::native
        Web1["Web Playback Module"]:::native
    end

    J["React Native Track Player Module (JS API Layer)"]:::js
    E["Example Applications (Usage Samples)"]:::example
    D["Documentation/Developer Tools"]:::docs
    B["Build and Configuration Files"]:::build

    %% Communication between JS API and native platforms
    J -->|"API_calls"| A1
    A1 -->|"Event_updates"| J

    J -->|"API_calls"| I1
    I1 -->|"Event_updates"| J

    J -->|"API_calls"| W1
    W1 -->|"Event_updates"| J

    J -->|"API_calls"| Web1
    Web1 -->|"Event_updates"| J

    %% Example usage and build configuration
    E -->|"Uses_API"| J
    J -->|"Initialization"| E

    B -->|"Configures"| J
    D -->|"References"| J

    %% Click Events
    click J "https://github.com/doublesymmetry/react-native-track-player/blob/main/src/TrackPlayerModule.ts"
    click A1 "https://github.com/doublesymmetry/react-native-track-player/tree/main/android/src/main/java/com/doublesymmetry/trackplayer"
    click I1 "https://github.com/doublesymmetry/react-native-track-player/tree/main/ios/RNTrackPlayer"
    click W1 "https://github.com/doublesymmetry/react-native-track-player/tree/main/windows/RNTrackPlayer"
    click Web1 "https://github.com/doublesymmetry/react-native-track-player/tree/main/web/TrackPlayer"
    click E "https://github.com/doublesymmetry/react-native-track-player/tree/main/example"
    click D "https://github.com/doublesymmetry/react-native-track-player/tree/main/docs"
    click B "https://github.com/doublesymmetry/react-native-track-player/blob/main/package.json"

    %% Styles
    classDef js fill:#f9f,stroke:#333,stroke-width:2px;
    classDef native fill:#ccf,stroke:#333,stroke-width:2px;
    classDef example fill:#cfc,stroke:#333,stroke-width:2px;
    classDef docs fill:#fc9,stroke:#333,stroke-width:2px;
    classDef build fill:#cff,stroke:#333,stroke-width:2px;
```
