• Preview: https://music.icodeq.com

---

Self Music is a music management and playback system for individuals and small teams. It provides an elegant UI and a smooth playback experience, supports playlist management, lyrics synchronization, artist/album data browsing, and has a built-in admin backend (JWT authentication), ready to use out of the box.

We offer three convenient deployment methods: Docker Run, Docker Compose, and BT Panel Deployment.

This is the easiest and fastest way to get started. You can run the entire application with just one command. (Note that due to data persistence requirements, the directory in which the command is started must be the same each time it is executed. It is recommended to execute it in the ~ directory).

Recommended for servers in China (using accelerated mirror):

docker run -d \
  --name self-music-app \
  --restart unless-stopped \
  -p 6230:80 \
  -v "$(pwd)/music_data":/data \
  docker.cnb.cool/onmicrosoft/self-music:latest

For overseas servers or local development (using official Docker Hub image):

docker run -d \
  --name self-music-app \
  --restart unless-stopped \
  -p 6230:80 \
  -v "$(pwd)/music_data":/data \
  zkeq/self-music:latest

• After starting, the application will be accessible at http://localhost:6230.
• All data (database, configuration files, music files) will be saved in the music_data folder in the current directory (restart the project after changing the password to update it automatically).
• Default administrator account: admin / admin123.

If you need more flexible configuration or want to do secondary development, you can use docker-compose.

1. Clone this project

   git clone https://github.com/zkeq/Self-music.git
   cd Self-music
   

2. Start the service

   docker-compose up -d
   

• After starting, the application will be accessible at http://localhost:8080.

---

• Modern UI: A beautiful interface based on shadcn/ui + Tailwind CSS 4, with support for light and dark theme switching.
• Complete Playback Experience: Supports playback queue, LRC lyrics synchronized scrolling, and random/loop playback modes.
• Multi-dimensional Browsing: Discover music by artist, album, playlist, mood, and more.
• Powerful Admin Panel: Built-in admin system with full CRUD operations for songs, artists, playlists, etc.
• Data Persistence: All data is persisted via volumes, making backups and migrations easy.

---

• Backend: FastAPI (Python) + SQLite
• Frontend: Next.js (React) + TypeScript + Tailwind CSS
• Containerization: Docker + Nginx

---

If you need to do secondary development, please set up your local environment as follows.

1. Prerequisites

   • Python 3.8+
   • Node.js 18+
   • pnpm (recommended)

2. Clone the project

   git clone https://github.com/zkeq/Self-music.git
   cd Self-music
   

3. Start the backend

   cd backend
   pip install -r requirements.txt
   uvicorn main:app --reload --host 0.0.0.0 --port 8000
   

   • The backend service runs at http://localhost:8000

4. Start the frontend

   cd ../frontend
   pnpm install
   pnpm dev
   

   • The frontend service runs at http://localhost:3000

---

• 🎨 Modern Design: Beautiful interface based on shadcn/ui + Tailwind CSS 4
• 📱 Responsive Layout: Seamlessly adapts to desktop and mobile
• 🔐 Secure Authentication: JWT-based login for the admin panel
• 🎧 Playback Experience: HTML5 audio + lyrics (LRC) parsing and synchronized scrolling
• 🎛️ Playback Controls: Progress, volume, shuffle, loop, previous/next
• 🌓 Theme Switching: Built-in dark mode (next-themes)

---

• 🎵 Playlists: Supports playback queue, playing from a list, and jumping to a specific song
• 📝 Lyrics Support: LRC/plain text parsing, supports full-screen lyrics with scrolling highlight
• 🔁 Playback Modes: Shuffle / list loop / single loop
• 💾 Local Storage: Playlists and state are persisted in localStorage

• 👤 Artists: List and details, songs/albums by the artist
• 💿 Albums: List and details, songs within an album
• 📂 Playlists: Browse and play public playlists
• 😊 Mood/Atmosphere: Display and filter by mood (backend support)

• ✅ Artists/Albums/Songs/Moods/Playlists: Full CRUD
• 🔃 Playlist Reordering: Supports custom ordering (returns in the saved order)
• 📦 Batch Import: Batch write song/album/artist information (including lyrics and audio URLs)
• 👤 Default Admin: admin / admin123

• 🛡️ JWT Authentication: Bearer Token for protected admin APIs
• 🌐 CORS Settings: Allows all origins by default

---

1. Upload the backend folder to the /root directory on your server.

2. Modify the configuration items jwt_secret and the password of the admin administrator in backend/config.yaml.

3. Open Pagoda Panel -> Websites -> Python Project -> Add Site. Create a new virtual environment.

4. Fill out the form as shown below.

5. After clicking confirm, the project will create the virtual environment and install dependencies. Wait for the installation to complete.

6. Click on settings to view the project log.

7. If you get an error that a dependency is not found, click on Terminal in the Actions column and manually enter pip install xxx (package name). If it says the port is occupied, change to an unused port in main.py.

8. Request the service port to check the running status. (If you see this string, the service is running normally).

9. The backend deployment is complete. You can now set up a reverse proxy with a domain on your CDN to go live.

• Follow the steps to deploy successfully.

---

Self-Music/
├── backend/                 # FastAPI + SQLite
│   ├── main.py              # API entrypoint (includes admin routes)
│   ├── user.py              # Public-facing user APIs
│   ├── music.db             # SQLite database
│   └── requirements.txt     # Python dependencies
├── frontend/                # Next.js + TypeScript + Tailwind CSS 4
│   ├── src/
│   │   ├── app/             # App routes (/play, /artists, /admin, etc.)
│   │   ├── components/      # UI components, player, lyrics, panels
│   │   ├── lib/             # API client, store, utils
│   │   └── styles/          # Global styles and themes
│   └── package.json         # Frontend dependencies and scripts
├── AGENTS.md                # Repository contribution and development guidelines (Chinese)
├── README.md                # Chinese README (this file)
└── README.en.md             # English README

---

• Public APIs (no login required)

  • GET /api/songs: Get songs with pagination
  • GET /api/songs/{id}: Song details
  • GET /api/songs/{id}/stream: Audio stream
  • GET /api/artists, /api/artists/{id}, /api/artists/{id}/songs, /api/artists/{id}/albums
  • GET /api/albums, /api/albums/{id}, /api/albums/{id}/songs
  • GET /api/playlists, /api/playlists/{id}

• Admin APIs (requires Bearer Token)

  • POST /api/auth/login: Admin login
  • GET/POST/PUT/DELETE /api/admin/{artists|albums|songs|moods|playlists}
  • PUT /api/admin/playlists/{id}/reorder: Reorder playlist
  • POST /api/admin/upload: Upload audio file
  • POST /api/admin/import/*: Batch import and duplicate check

See the Swagger docs at /docs after running the backend for details.

---

• Before submitting, ensure: builds pass, pnpm lint passes, API runs locally
• Follow the repository conventions (see AGENTS.md)
• Contributions are welcome: Bug reports, feature proposals, documentation improvements, internationalization support

---

This project is licensed under the MIT License.

---

Thanks to @haorwen for providing the NetEase Cloud Music metadata API service for this project.

---