vd39/subsonic-player repository overview

⁠🎵 Subsonic Player: A Modern Subsonic Client

⁠📝 Overview

Subsonic player is a responsive, modern web-based client designed for Subsonic music servers⁠.

Built with Nuxt 4⁠, a modern Vue 3⁠ framework, this open-source application provides a seamless and enjoyable music listening experience across all devices.

Compatible Servers:

• Gonic⁠ (This application is primarily optimized for use with Gonic⁠).
• Airsonic Advanced⁠.
• Navidrome⁠.
• Subsonic servers⁠.

⁠✨ Features

1. Fully Responsive UI (Further design improvements are ongoing.)

   • Optimized for desktop and mobile devices.
   • Adaptive design.

2. Comprehensive Library Browsing

   • Browse by album, artist, genre, and folder/files.
   • Explore podcasts and favourites.
   • Access internet radio stations.

3. Advanced Functionality

   • Bookmarking podcast episode to keep track of the listening position across multiple sessions.
   • MediaSession Integration.
   • Advanced Search capabilities.
   • Dark/Light Mode support.
   • Keyboard shortcuts (Press Ctrl + / to open or close the shortcuts modal). Single-key shortcuts do not run while focus is in an input field.
   • Context menu access via right-click (desktop) or long press (mobile) for quick actions on tracks, albums, playlists, and more.
   • Easily drag and drop your favorite tracks, albums, and podcast episodes right into the queue or your playlist in the sidebar (available only on desktop).

4. Progressive Web App (PWA) Feature

   • Seamlessly download the app icon to the home screen, providing the convenience of launching the app just like a traditional native application.
   • Benefit from a web-based app that reduces storage space on devices compared to traditional downloadable applications, while still providing robust functionality.

5. Settings

   • The app includes settings for theme, layout, crossfade, replay gain, scrobbling, and more. See the environment variables⁠ section for which can be pre-configured across all devices.

⁠📷 Previews

Click on the images to see video of the app in action.

⁠Dark theme

Desktop	Mobile

⁠Light theme

Desktop	Mobile

⁠🚀 Installation Methods

Prerequisites:

• Docker⁠ (recommended).
• Node.js⁠ 20+.
• npm⁠.

⁠Method 1: Docker Deployment

⁠Docker Compose Configuration

The simplest way to run the application is via Docker Compose. This method automatically handles dependencies and configuration.

The environment variables⁠ are optional and can be customized as needed.

Create a file named docker-compose.yml with the following content.

services:
  subsonic-player:
    container_name: subsonic-player
    image: vd39/subsonic-player:latest
    ports:
      - '3000:3000'
    restart: unless-stopped

Execute the following command in your terminal:

docker compose up -d

The application will be accessible at http://localhost:3000.

⁠Preview Version

A preview version (vd39/subsonic-player:preview) is available for those who want to try the latest changes early. Note that this version contains changes that are still undergoing internal testing and may contain bugs or stability issues. Use at your own risk.

image: vd39/subsonic-player:preview

⁠Docker Run Command (Alternative)

This method offers more granular control.

docker run -d \
  --name subsonic-player \
  -p 3000:3000 \
  --restart unless-stopped \
  vd39/subsonic-player:latest

The application will be accessible at http://localhost:3000.

⁠Method 2: Static SPA Export

Pre-built static SPA archives are published as GitHub Releases⁠. Each release contains a .tar.gz tarball that can be served by any static file host (Nginx, Caddy, Apache, S3, etc.).

1. Download the latest tarball from the Releases⁠ page.

2. Extract the archive:

   tar -xzvf subsonic-player-static-*.tar.gz -C /var/www/subsonic-player
   

   Copy

3. Serve the extracted directory with your preferred static file server.

⁠Method 3: Local Development

This method skips Docker and runs the application directly using Node.js and npm.

1. Clone the repository:

   git clone https://github.com/VD39/subsonic-player.git
   

   Copy

2. Navigate to the project directory:

   cd subsonic-player
   

   Copy

3. Install dependencies:

   npm install
   

   Copy

4. (Optional) Create a .env file: Create a file named .env in the project's root directory. This file will hold your environment variables⁠.

5. Start the development server:

   npm run dev
   

   Copy

The development server will start at http://localhost:3000.

Changes you make to the code will automatically trigger a rebuild and refresh of the browser.

⁠🔧 Environment Variables

Settings in this application can be configured at two levels. Environment variables establish default values that apply to all users across all devices (ideal for Docker deployments sharing a single server). These defaults can be overridden at an individual user level via localStorage when a setting is changed in the UI; the environment variable then acts as the fallback value.

All environment variables are optional. NUXT_PUBLIC_SERVER_URL pre-fills the server URL so users can bypass entry at the login screen. Every other variable defines an app default that users can subsequently override in the UI.

⁠Connection & Build

⁠Settings

⁠🤝 Contributing

Contributions are always welcome! Feel free to contribute, provide feedback, or raise issues on GitHub!

⁠📄 License

This project is licensed under the GPL-3.0 license. Full license details available in the LICENSE⁠ file for details.

⁠🌐 Project Resources

• GitHub Repository⁠
• Docker Hub⁠