🎵 Streamable Cloud Music Server via VLC

Turn your public GitHub repository into a free, automated personal cloud music server that streams directly to VLC on your phone, PC, or tablet.

---

🚀 How It Works

1. Upload: You add .mp3, .wav, .m4a, .flac, or .ogg files to the mp3files/ directory.
2. Automate: A GitHub Action automatically triggers, scans your files, builds a playlist.m3u file, and updates it on GitHub.
3. Stream: VLC loads the playlist.m3u file from GitHub's serverless CDN and streams the audio.

---

🎵 Current Music Library

Music	By	Duration
Africa	Toto	04:55
Blue Neon	Projekt F	03:38
Boundary	Krosia	03:32
Can I Call You Tonight	Dayglow	03:31
Down Under	Men At Work	03:42
Dreams (Islam Makhachev UFC Walkout)	DJ Nariman	02:18
Jet Lag	Simple Plan ft. Natasha Bedingfield	03:24
Lost Highway (Instrumental)	NightCrawl	03:55
Magic In The Air	MAGIC SYSTEM feat. Chawki	03:53
Magomed Ankalaev UFC Walkout Song	Magomed Ankalaev	02:24
Ordinary	Ordinary	03:17
Ordinary (Slowed)	Ordinary	03:30

---

🛠️ Step-by-Step Setup

Step 1: Create a Public GitHub Repository

1. Go to GitHub and create a new public repository (e.g., my-cloud-music).
2. Make sure it is Public so VLC can access the stream link without credentials.

Step 2: Push these Files to GitHub

Initialize Git in this local folder and push it to your new repository:

git init
git add .
git commit -m "Initial setup"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git
git push -u origin main

Example:

https://raw.githubusercontent.com/pakcli/github-music-server/main/playlist.m3u

Step 3: Enable Workflows Write Permissions

By default, GitHub Actions might not have permission to write changes (like playlist.m3u) back to your repository. Enable it:

1. In your GitHub repository, click on Settings (top tabs).
2. Go to Actions > General on the left sidebar.
3. Scroll down to Workflow permissions.
4. Select Read and write permissions.
5. Click Save.

Step 4: Stream in VLC!

Once the GitHub Action runs (which it will when you add files to mp3files/), copy your raw playlist link:

1. Go to your repository on GitHub.
2. Find playlist.m3u and click on it.
3. Click the Raw button in the top right of the file view.
4. Copy the URL from your browser's address bar. It will look like this: https://raw.githubusercontent.com/YOUR_USERNAME/YOUR_REPO_NAME/main/playlist.m3u
5. Open VLC:
   • PC/Mac: Press Ctrl+N (or Cmd+N on Mac) / Go to Media -> Open Network Stream...
   • Mobile: Go to Network -> Open Network Stream / Stream
6. Paste the raw URL and press Play!

---

📴 Offline / Local Network Streaming

If you lose internet connection or do not want to use cellular data/internet, you can still play and stream your music locally. The playlist playlist.m3u uses plain relative paths with literal spaces (no %20 URL-encoding), which makes it fully offline-compatible with VLC on all devices.

Option A: Play Directly on this PC (100% Offline, No Server)

No server is required to play your music locally on the PC where the files are stored:

1. Open your file explorer and navigate to the project directory.
2. Double-click the playlist.m3u file (or right-click and open with VLC).
3. Since the playlist uses relative file paths with literal spaces, VLC resolves and plays all files directly from your disk offline!

Option B: Play Directly on Phone/Tablet (100% Offline, No Server)

You can play your music fully offline on your mobile device (phone or tablet) without running a local server:

1. Copy the playlist.m3u file and the mp3files/ directory from your PC to your phone/tablet storage (keep them in the same parent directory so relative paths remain valid).
2. Open VLC on your phone/tablet, navigate to directories, and open the playlist.m3u file.
3. VLC will resolve the literal file paths and play the files directly from your device's local storage.

Option C: Stream to other devices (Phone/Tablet) on Local Wi-Fi

If you want to stream the music from your PC to other devices on the same Wi-Fi network without using the internet:

1. Open PowerShell in this folder.
2. Run the start script:

   .\start.ps1

3. The script will:
   • Automatically scan and fix file extensions in the mp3files/ directory by inspecting their binary headers (e.g., correcting M4A files incorrectly named .mp3 so VLC plays them correctly).
   • Regenerate the local playlist.m3u file.
   • Start a local HTTP server on port 8000.
4. Copy the network URL printed by the script (e.g., http://192.168.x.x:8000/playlist.m3u or the mDNS hostname http://<computer-name>.local:8000/playlist.m3u).
5. Open VLC on your phone/tablet, go to Network Stream, paste that local URL, and start listening! (VLC will automatically handle URL-encoding for the network requests over the local Wi-Fi connection).

---

⚙️ How to Add Music in the Future

1. Add your new music files to the mp3files/ directory.
2. Run .\start.ps1 locally to automatically fix any wrong file extensions and regenerate the local playlist.m3u.
3. Commit and push your changes to GitHub. The GitHub Action will automatically run to update the online playlist so VLC can sync the next time you stream!