Skip to content

About

Cross-Platform Audio Streaming Suite, Native Android App & PC Web Server

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

2 Commits

Folders and files

Repository files navigation

πŸ΄β€β˜ οΈ TortugaMusic

Cross-Platform Audio Streaming Suite, Offline Player & Media Cloud

License: MIT Android Python Flask Chaquopy Telegram


TortugaMusic is a complete, dual-platform audio streaming and media suite designed for both Android (Native APK with embedded Python engine via Chaquopy) and PC / Home Server (Flask + Web Player) with automated Telegram mirror synchronizers and Cloudflare tunnel remote access.


Note

DISCLAIMER & LEGAL NOTICE
TortugaMusic is an open-source educational media framework. It does not host copyrighted media files. Streaming features query public endpoints and indexers. Users are solely responsible for ensuring compliance with copyright and local regulations when accessing media.


πŸ“‹ Table of Contents


πŸ—οΈ Ecosystem & Architecture

flowchart TD
    subgraph ANDROID ["πŸ“± Android Native App (v3.6)"]
        UI_A["Native Android UI (Kotlin/Java)"]
        CHAQUO["Chaquopy Embedded Python Engine"]
        CACHE_A["Local Audio & Media Cache"]
        BG_PLAY["Background Playback & Notification Controls"]
        UI_A <--> CHAQUO
        CHAQUO <--> CACHE_A
    end

    subgraph PC ["πŸ’» PC / Home Server Edition"]
        WEB_UI["Responsive HTML5 Web Player"]
        FLASK["Flask Python Backend (Port 5000)"]
        PROXY["Smart Stream Proxy & Scrapers"]
        DB[(SQLite / tortuga_cache.db)]
        WEB_UI <--> FLASK
        FLASK <--> PROXY
        FLASK <--> DB
    end

    subgraph SYNC ["πŸ€– Automation & Remote Access"]
        TG_BOT["Telegram SC Mirror Bot (Telethon)"]
        TUNNEL["Cloudflare Auto-Tunnel"]
        GIST["GitHub Gist Dynamic Sync"]
        WORKER["Cloudflare Worker Redirector"]
        TG_BOT -->|Auto-Detect New Domains| GIST
        TUNNEL -->|Dynamic IP/Tunnel Update| GIST
        GIST -->|Live Resolution| WORKER
    end

    CHAQUO <-->|Sync API| GIST
    WEB_UI <-->|Remote Stream| WORKER
Loading

πŸ“± Android Edition (APK Direct Download)

The native Android app brings the full power of TortugaMusic directly to your phone:

  • Background Audio Playback: Listen to music and podcasts continuously with the screen turned off.
  • Lock Screen & Notification Controls: Integrated media session notification with play, pause, skip, and album art.
  • Embedded Python Runtime: Runs scrapers and audio extractors locally on-device without needing an external server.
  • Offline Caching: Download your favorite tracks and playlists locally for offline listening.

πŸ“₯ Download & Install APK

  1. Download the latest official release: πŸ‘‰ TortugaMusic-v3.6-Release.apk (72.5 MB, Android 7.0+)
  2. On your Android phone, open the downloaded APK file.
  3. If prompted, allow "Install from unknown sources" in your browser or file manager settings.
  4. Tap Install and launch TortugaMusic!

πŸ’» PC & Web Server Setup

The PC edition runs a local web application that can be used on your computer or hosted on a local server.

Prerequisites

Step-by-Step Installation

  1. Clone the repository:

    git clone https://github.com/robinandreoni/TortugaMusic.git
    cd TortugaMusic/PC
  2. Create a virtual environment (recommended):

    # On Windows:
    python -m venv venv
    venv\Scripts\activate
    
    # On Linux / macOS:
    python3 -m venv venv
    source venv/bin/activate
  3. Install dependencies:

    pip install -r requirements.txt
  4. Launch the Server:

    • On Windows (1-Click): Double click AVVIA_TORTUGA_PC.bat
    • Or via Terminal:
      python run.py
  5. Open in Browser: Navigate to http://localhost:5000


πŸ€– Telegram Mirror Bot Setup Guide

The optional Telegram bot monitors community mirrors and channels to ensure dynamic scrapers always point to working domains.

Important

No personal credentials are stored in this repository. To run the Telegram bot, you must configure your own Telegram API credentials.

How to get your Telegram API credentials:

  1. Go to my.telegram.org and log in with your phone number.
  2. Click on API development tools.
  3. Fill in the application form (any app name and short name will do).
  4. Telegram will generate two values:
    • App api_id (a number, e.g. 12345678)
    • App api_hash (a hexadecimal string)

Configuring the Bot:

  1. In PC/, copy .env.example to .env:
    cp .env.example .env
  2. Open .env and fill in your values:
    TELEGRAM_API_ID=12345678
    TELEGRAM_API_HASH=your_telegram_api_hash_here
    TELEGRAM_GROUP_LINK=https://t.me/your_target_channel
    
    # Optional GitHub Gist sync
    GITHUB_TOKEN=your_github_personal_access_token
    GIST_ID=your_gist_id
    GITHUB_USERNAME=your_github_username
  3. Run the bot:
    • Windows: Double-click START_BOT.bat
    • Linux / Mac: python telegram_sc_bot.py
  4. The first time you launch, Telethon will ask for your phone number and login code in the console. The session will be saved locally in sc_bot_session.session (automatically ignored by git).

🌐 Cloudflare Tunnel & Mobile Remote Access

Want to access your home PC's TortugaMusic library from anywhere in the world on your smartphone?

  1. Install Cloudflared (developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).
  2. Run AVVIA_TORTUGA_ONLINE.bat (Windows) or ./AVVIA_TORTUGA_ONLINE.sh (Android Termux).
  3. The script starts a secure zero-configuration tunnel and automatically syncs the live URL to your Cloudflare Worker gateway (see cloudflare_worker.js).
  4. Read GUIDA_AVVIO_DA_TELEFONO.md for the complete guide on running the server directly inside Android Termux!

πŸ› οΈ Building Android App from Source

To compile the Android APK or AAB bundle yourself:

  1. Open Android Studio (Hedgehog or newer recommended).
  2. Select Open an existing project and choose the android/ directory.
  3. Ensure Android SDK 35/36 and JDK 17 are configured in Project Structure.
  4. Let Gradle sync and download Chaquopy dependencies.
  5. In the menu, click Build $\rightarrow$ Build Bundle(s) / APK(s) $\rightarrow$ Build APK(s).
  6. The generated APK will be placed in android/app/build/outputs/apk/release/.

πŸ“ Project Layout

TortugaMusic/
β”œβ”€β”€ TortugaMusic-v3.6-Release.apk   # Ready-to-install Android Release APK
β”œβ”€β”€ build_release.py                # Automated version & APK/AAB build script
β”œβ”€β”€ BUILD_RELEASE.bat               # 1-Click release compiler
β”œβ”€β”€ PlayStore_Assets/               # High-res icons, banners & promotional artwork
β”œβ”€β”€ android/                        # Android Studio native app source
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ src/main/java/          # Android Native Activities & Services
β”‚   β”‚   β”œβ”€β”€ src/main/python/        # Embedded Chaquopy Python Engine
β”‚   β”‚   β”œβ”€β”€ src/main/res/           # Layouts, themes, drawables & media styles
β”‚   β”‚   └── build.gradle
β”‚   β”œβ”€β”€ build.gradle
β”‚   └── settings.gradle
└── PC/                             # Web Player & Local Python Server
    β”œβ”€β”€ backend/                    # Scrapers, SQLite database, audio proxy
    β”œβ”€β”€ frontend/                   # HTML5 Audio/Video player and CSS styles
    β”œβ”€β”€ data/                       # Local playlists and catalog seeds
    β”œβ”€β”€ .env.example                # Template for Telegram & Gist credentials
    β”œβ”€β”€ run.py                      # Local server entry point
    β”œβ”€β”€ auto_tunnel.py              # Cloudflare Tunnel auto-synchronizer
    β”œβ”€β”€ cloudflare_worker.js        # Worker script for permanent domain routing
    β”œβ”€β”€ telegram_sc_bot.py          # Telethon mirror detector
    β”œβ”€β”€ AVVIA_TORTUGA_PC.bat        # 1-Click launcher (Local PC)
    β”œβ”€β”€ AVVIA_TORTUGA_ONLINE.bat    # 1-Click launcher (Cloudflare Tunnel)
    β”œβ”€β”€ AVVIA_TORTUGA_ONLINE.sh     # Android Termux mobile launcher
    └── requirements.txt            # Python dependencies

πŸ“„ License

This project is licensed under the MIT License β€” see the LICENSE file for details.
Created by Robin Andreoni & Tortuga Italia.

About

Cross-Platform Audio Streaming Suite, Native Android App & PC Web Server

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages