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.
- Ecosystem & Architecture
- π± Android Edition (APK Direct Download)
- π» PC & Web Server Setup
- π€ Telegram Mirror Bot Setup Guide
- π Cloudflare Tunnel & Mobile Remote Access
- π οΈ Building Android App from Source
- π Project Layout
- π License
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
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 the latest official release: π TortugaMusic-v3.6-Release.apk (72.5 MB, Android 7.0+)
- On your Android phone, open the downloaded APK file.
- If prompted, allow "Install from unknown sources" in your browser or file manager settings.
- Tap Install and launch TortugaMusic!
The PC edition runs a local web application that can be used on your computer or hosted on a local server.
- Python 3.10+ (python.org)
- Git
-
Clone the repository:
git clone https://github.com/robinandreoni/TortugaMusic.git cd TortugaMusic/PC -
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
-
Install dependencies:
pip install -r requirements.txt
-
Launch the Server:
- On Windows (1-Click): Double click
AVVIA_TORTUGA_PC.bat - Or via Terminal:
python run.py
- On Windows (1-Click): Double click
-
Open in Browser: Navigate to
http://localhost:5000
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.
- Go to my.telegram.org and log in with your phone number.
- Click on API development tools.
- Fill in the application form (any app name and short name will do).
- Telegram will generate two values:
App api_id(a number, e.g.12345678)App api_hash(a hexadecimal string)
- In
PC/, copy.env.exampleto.env:cp .env.example .env
- Open
.envand 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
- Run the bot:
- Windows: Double-click
START_BOT.bat - Linux / Mac:
python telegram_sc_bot.py
- Windows: Double-click
- 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).
Want to access your home PC's TortugaMusic library from anywhere in the world on your smartphone?
- Install Cloudflared (developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).
- Run
AVVIA_TORTUGA_ONLINE.bat(Windows) or./AVVIA_TORTUGA_ONLINE.sh(Android Termux). - The script starts a secure zero-configuration tunnel and automatically syncs the live URL to your Cloudflare Worker gateway (see
cloudflare_worker.js). - Read
GUIDA_AVVIO_DA_TELEFONO.mdfor the complete guide on running the server directly inside Android Termux!
To compile the Android APK or AAB bundle yourself:
- Open Android Studio (Hedgehog or newer recommended).
- Select Open an existing project and choose the
android/directory. - Ensure Android SDK 35/36 and JDK 17 are configured in Project Structure.
- Let Gradle sync and download Chaquopy dependencies.
- In the menu, click Build
$\rightarrow$ Build Bundle(s) / APK(s)$\rightarrow$ Build APK(s). - The generated APK will be placed in
android/app/build/outputs/apk/release/.
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
This project is licensed under the MIT License β see the LICENSE file for details.
Created by Robin Andreoni & Tortuga Italia.