#+ 🎵 Self Music - Personal Music Library

---

Self Music is a personal music system designed for individuals or small teams. It offers an elegant UI, smooth playback, playlist management, synced lyrics, and public browsing of artists/albums/playlists. An admin console with JWT authentication is built in.

• 🎨 Modern UI: shadcn/ui + Tailwind CSS 4
• 📱 Responsive Layout: desktop and mobile friendly
• 🔐 Secure Admin: JWT-protected admin console
• 🎧 Playback: HTML5 audio with LRC/plaintext lyric parsing and synchronized scrolling
• 🎛️ Controls: progress, volume, shuffle, repeat, previous/next
• 🌓 Theme: light/dark modes via next-themes

---

• 🎵 Playlists: queue support, play from list, jump to song
• 📝 Lyrics: LRC/plain text parsing, full-screen lyrics with scrolling highlight
• 🔁 Modes: shuffle / list repeat / single repeat
• 💾 Local persistence: playlist and state via localStorage
• ⚡ Streaming: backend serves local audio files with Accept-Ranges

• 👤 Artists: list/detail, artist songs and albums
• 💿 Albums: list/detail, album songs
• 📂 Playlists: browse public playlists and play
• 😊 Moods: mood-based categorization (backend support)

• ✅ Full CRUD for artists, albums, songs, moods, playlists
• 🔃 Playlist reorder: maintain custom order in responses
• ⬆️ File upload: audio file uploads stored under /uploads
• 📦 Batch import: import song/album/artist with lyrics and audio URLs
• 👤 Default admin: admin / admin123

• 🛡️ JWT auth: Bearer token for admin endpoints
• 🌐 CORS: permissive in dev; restrict in production

---

• 🐍 FastAPI ^0.104
• 🚀 Uvicorn ^0.24
• 💾 SQLite (backend/music.db)
• 🔐 PyJWT + HTTP Bearer
• 🎼 Mutagen (audio metadata)
• 📦 python-multipart (uploads)

• ⚛️ Next.js 15.4.x + React 19
• 📘 TypeScript ^5
• 🎨 Tailwind CSS 4
• 🧩 shadcn/ui + Radix UI
• 🗃 Zustand (state)
• 🌗 next-themes (theme)
• 🎬 framer-motion (animation)

---

• 🐍 Python 3.8+
• 📦 Node.js 18+
• 🔧 Package manager: pnpm (or npm)

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

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

• API: http://localhost:8000
• Docs: http://localhost:8000/docs
• Default admin: admin / admin123

In production, configure a secure SECRET_KEY and restrict CORS to trusted origins.

cd ../frontend
pnpm install   # or npm install
# Optional (defaults to http://localhost:8000/api):
# echo "NEXT_PUBLIC_API_URL=http://localhost:8000/api" > .env.local
pnpm dev       # or npm run dev

• App: http://localhost:3000

• 🏠 Home: /
• 🎧 Player: /play and /play/[id]
• 🎵 Songs: /songs
• 👤 Artists: /artists and /artist/[id]
• 💿 Albums: /albums (if enabled)
• 📂 Playlists: /playlists and /playlist/[id]
• 🔐 Admin Login: /admin/login

---

Self-Music/
├── backend/
│   ├── main.py
│   ├── user.py
│   ├── music.db
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   ├── components/
│   │   ├── lib/
│   │   └── styles/
│   └── package.json
├── AGENTS.md
├── README.md        # Chinese
└── README.en.md     # English (this file)

---

• Public

  • GET /api/songs • GET /api/songs/{id} • GET /api/songs/{id}/stream
  • GET /api/artists • GET /api/artists/{id} • GET /api/artists/{id}/songs • GET /api/artists/{id}/albums
  • GET /api/albums • GET /api/albums/{id} • GET /api/albums/{id}/songs
  • GET /api/playlists • GET /api/playlists/{id}

• Admin (Bearer token)

  • POST /api/auth/login
  • CRUD at /api/admin/{artists|albums|songs|moods|playlists}
  • PUT /api/admin/playlists/{id}/reorder
  • POST /api/admin/upload
  • POST /api/admin/import/*

See Swagger at /docs when backend is running.

---

• Backend fails to start
  • Check Python version and dependencies
  • Ensure port 8000 is free
• Audio not playing
  • songs.audioUrl must be a valid local path
  • File exists and server can read it
• CORS errors
  • Dev is permissive; restrict origins in production
• CSS issues
  • Reinstall deps or verify Tailwind setup

---

• Backend
  • Run with uvicorn/gunicorn behind Nginx/Caddy
  • Configure SECRET_KEY, restrict CORS, persist music.db and uploads/
• Frontend
  • Any static host or Vercel
  • Set NEXT_PUBLIC_API_URL to your API, e.g., https://api.example.com/api

---

• Ensure builds pass, pnpm lint is clean, and API runs locally
• Follow repository conventions in AGENTS.md
• Welcome: bug reports, feature requests, docs improvements, i18n

---

MIT License — see LICENSE.

---