Resonix

Resonix is your personal, ad-free music player that gives you complete control over your collection. Add your favorite tracks, organize them your way, and enjoy a seamless listening experience—completely yours, with no interruptions.

---

Table of Contents

• Resonix
  • Resonix-server
  • 🛠 Tech Stack
  • 🚀 Features
  • 📂 Project Structure
  • ⚡ Getting Started
    • Prerequisites
    • Run with Docker 🐳
    • Adding Music to Resonix
  • 📚 API Endpoints
  • 📜 License
    • Contributions & Support

---

Resonix-server

This repository contains the server-side code for Resonix (see Resonix App). The server is responsible for handling authentication, managing the music library, processing metadata, serving high-quality audio streams, and providing personalized recommendations.

---

🛠 Tech Stack

• Go (Golang) – High-performance backend
• Gin – Lightweight and fast web framework
• Pgx – PostgreSQL driver for database interactions
• Docker – Containerized deployment
• Docker Compose – Multi-container orchestration
• PostgreSQL – Database for storing tracks, metadata, and user info

---

🚀 Features

✅ Self-Hosted & Ad-Free – Full control over your music
✅ Easy Track Management – Put your musics to seeds folder, and start importing!
✅ Smart Recommendations – Personalized suggestions based on listening history
✅ Multi-User Support – Profiles, preferences, and separate libraries
✅ Scalable & Performant – Optimized queries and async processing

---

📂 Project Structure

resonix-server/
│── data/                    # Persistent data storage
│   ├── media/               # Media files
│       ├── covers/          # Album and track cover images
│       ├── system/          # System files (fixed playlist cover, etc)
│       ├── tracks/          # Uploaded audio files
│── internal/                # Core business logic and functionalities
│   ├── api/                 # API request handlers
│   ├── middleware/          # Middleware functions (authentication, logging, etc.)
│   ├── model/               # Data models and schema definitions
│   ├── repository/          # Database queries and interactions
│   ├── seed/                # Data seeding for tracks, users, and albums
│   ├── service/             # Core services (business logic, database layer)
│   ├── storage/             # File storage and processing logic
│   ├── util/                # Utility functions and helpers
│── seeds/                   # Sample media files (FLAC, MP3) for testing
│── main.go                  # Server entry point
│── Dockerfile               # Docker configuration for containerization
│── go.mod                   # Dependency management with Go modules
│── README.md                # Project documentation

---

⚡ Getting Started

Prerequisites

Ensure you have the following installed:

• Docker & Docker Compose

---

Run with Docker 🐳

1️⃣ Create a docker-compose.yml file

• Copy the contents of docker/docker-compose.yaml and save it as docker-compose.yml in any directory.

2️⃣ Modify environment variables

• Edit the relevant environment variables inside the docker-compose.yml file to suit your setup.

3️⃣ Start the server using Docker Compose

docker-compose up -d

4️⃣ Create the database schema

• Stop only the server container:

  docker-compose stop resonix-server

• Run the following command to create the database schema:
• Copy the contents of db.sql and save it as db.sql in the same directory as docker-compose.yml.
• Run the following command to create the database schema:

  docker exec -i resonix-postgres psql -U <your username> -d resonix < db.sql

• Run the command above one more time
• Start the server again:

  docker-compose start resonix-server

---

Here’s a corrected and improved version of your steps:

---

Adding Music to Resonix

1️⃣ Stop the server container:

docker-compose stop resonix-server

2️⃣ Add music files to the seed directory specified in docker-compose.yml.

3️⃣ Update the SEED_TRACKS environment variable:

• Edit docker-compose.yml, setting:

  SEED_TRACKS=true

• Or use a command to update it directly:

  sed -i 's/SEED_TRACKS=false/SEED_TRACKS=true/' docker-compose.yml  # Linux

4️⃣ Apply database updates (set album covers & search vectors):

docker exec -i resonix-postgres psql -U <your_username> -d resonix < db.sql

🔹 Replace <your_username> with the actual PostgreSQL username.

5️⃣ Restart the server with the updated configuration:

docker-compose up -d --force-recreate --no-deps resonix-server

⚠️ Note: For complete metadata, please use music files with embedded metadata. (you'll see artist, track numbers, album, cover in the file properties)

📚 API Endpoints

Method	Endpoint	Description
User
GET	/user/	Get the authenticated user's profile.
GET	/user/library	Retrieve the user's music library.
GET	/user/:id	Get details of a specific user by ID.
GET	/user/:id/followers	Get a list of a user's followers.
GET	/user/:id/following	Get a list of users a user is following.
GET	/user/:id/playlist	Retrieve playlists owned by a user.
POST	/user/change-password	Update the authenticated user's password.
POST	/user/change-nickname	Change the authenticated user's nickname.
Session
POST	/session/login	Authenticate and log in a user.
POST	/session/register	Register a new user account.
Storage
GET	/storage/track/:id	Retrieve a track's audio file.
GET	/storage/cover/track/:id	Retrieve a track's cover image.
GET	/storage/cover/album/:id	Retrieve an album's cover image.
GET	/storage/cover/playlist/:id	Retrieve a playlist's cover image.
Album
GET	/album/	Get a list of albums.
GET	/album/:id	Get details of a specific album.
GET	/album/:id/tracks	Retrieve tracks from a specific album.
Search
GET	/search/	Search for tracks, albums, or artists.
Recommendations
GET	/recommendation/	Get personalized recommendations.
POST	/recommendation/personalized/next	Get the next track recommendations.
Playlist
POST	/playlist/	Create a new playlist.
GET	/playlist/	Retrieve playlists for the authenticated user.
GET	/playlist/:id	Get details of a specific playlist.
GET	/playlist/:id/tracks	Retrieve tracks in a specific playlist.
POST	/playlist/:id/tracks	Add a track to a playlist.
DELETE	/playlist/:id/tracks	Remove a track from a playlist.
Activity
POST	/activity/playing	Update the currently playing track.
POST	/activity/track/:id/like	Like a track.
POST	/activity/album/:id/like	Like an album.
POST	/activity/playlist/:id/follow	Follow a playlist.
POST	/activity/artist/:id/follow	Follow an artist.
POST	/activity/user/:id/follow	Follow a user.
Artist
GET	/artist/:id	Get details of a specific artist.
GET	/artist/:id/albums	Retrieve albums by a specific artist.
GET	/artist/:id/albums/top	Retrieve top albums by an artist.
GET	/artist/:id/tracks	Retrieve tracks by a specific artist.
GET	/artist/:id/tracks/top	Retrieve top tracks by an artist.
Track
GET	/track/:id/liked	Check if a track is liked by the user.

---

📜 License

This project is licensed under the MIT License. See the LICENSE file for more details.

---

Contributions & Support

💡 Contributions are welcome! Feel free to open issues and submit PRs.
🚀 Star this repo if you find it useful!

---