How To Install Feishin on Debian 12

Installing Feishin on your Debian 12 system provides a modern, feature-rich solution for streaming and managing your music collection. As an open-source self-hosted music player, Feishin delivers a sleek interface and powerful capabilities that make it a compelling alternative to mainstream music applications. This comprehensive guide will walk you through everything you need to know about installing and configuring Feishin on Debian 12, ensuring you get the most out of this exceptional music player.

Introduction

Feishin represents a significant evolution in self-hosted music players. Originally a rewrite of Sonixd, Feishin has developed into a robust application with multiple playback options and a modern user interface. For Debian 12 users, Feishin offers an elegant solution to access and stream music from compatible servers like Jellyfin and Navidrome.

The application stands out with its dual playback engines-MPV and web player backends-giving users flexibility in how they interact with their music libraries. Whether you prefer the powerful features of the MPV player or the convenience of web-based playback, Feishin accommodates your needs while maintaining a consistent user experience.

This guide covers multiple installation methods, configuration options, and troubleshooting tips specifically tailored for Debian 12 users. By the end, you’ll have a fully functional Feishin setup that delivers high-quality music playback and seamless integration with your existing music server infrastructure.

Understanding Feishin and Its Features

Before diving into installation procedures, it’s worth exploring what makes Feishin stand out among self-hosted music players.

Core Features

Feishin brings a comprehensive set of features that elevate your music listening experience:

• MPV Player Backend: Leverages the powerful MPV media player for superior audio playback quality and format support
• Web Player Backend: Offers flexibility with browser-based playback options
• Modern User Interface: Clean, intuitive design that makes navigating large music collections effortless
• Scrobbling Capabilities: Track your listening habits by scrobbling playback data to your server
• Smart Playlist Editor: Create dynamic playlists that update automatically (specifically for Navidrome)
• Lyrics Support: Both synchronized and unsynchronized lyrics display options
• Cross-Platform Compatibility: Available for Linux, Windows, and macOS

Compared to other music players like Plex and Jellyfin’s built-in music features, Feishin focuses exclusively on music, resulting in a more refined and specialized experience. The application’s development is ongoing, with active work on a major rewrite to further improve functionality and performance.

Feishin’s open-source nature means it benefits from community input and transparent development. It’s designed to work with existing music server solutions rather than replacing them, functioning as a client that connects to your Jellyfin or Navidrome server.

Prerequisites for Installing Feishin on Debian 12

Ensuring your Debian 12 system meets all requirements will streamline the installation process and prevent potential issues. Here’s what you’ll need before proceeding:

System Requirements

• Debian 12 (Bookworm) installation with administrative privileges
• At least 2GB of RAM (4GB recommended for larger libraries)
• 50MB of free disk space (more needed for caching larger music libraries)
• Active internet connection for downloading packages

Setting Up Your Environment

Begin by updating your system’s package index and upgrading installed packages:

sudo apt update
sudo apt upgrade -y

Next, install essential packages required by Feishin:

sudo apt install software-properties-common apt-transport-https ca-certificates curl gnupg -y

Installing MPV (Required)

MPV is essential for optimal Feishin performance. Install it using:

sudo apt install mpv -y

After installation, verify MPV is working correctly:

mpv --version

The command should display the installed MPV version. Note the location of the MPV binary, typically /usr/bin/mpv, as you’ll need this path when configuring Feishin.

Creating a Non-Root User (If Needed)

If you’re starting with a fresh Debian installation, create a non-root user with sudo privileges:

sudo adduser username
sudo usermod -aG sudo username

Replace “username” with your preferred username.

Installation Methods Overview

Feishin offers several installation options for Debian 12, each with distinct advantages. Understanding these methods will help you choose the most appropriate approach for your needs.

• Desktop Client Installation

The recommended method for most users, the desktop client provides the full Feishin experience with support for both MPV and web player backends. This approach offers the most comprehensive feature set, including built-in lyrics fetching capabilities.

• AppImage Installation

The AppImage method provides excellent portability and eliminates dependency conflicts. This self-contained executable runs without traditional installation, making it easy to use across different Linux distributions including Debian 12.

• Docker Installation

For users comfortable with containerization, the Docker installation method offers isolation and simplified management. This approach is particularly useful in server environments or when you want to minimize impact on your host system.

Each method has its strengths-desktop client for feature completeness, AppImage for simplicity, and Docker for isolation. The following sections will guide you through each installation approach in detail.

Method 1: Installing Feishin Desktop Client on Debian 12

The desktop client offers the most comprehensive Feishin experience and is the recommended option for most Debian 12 users. Follow these steps for a successful installation:

Downloading the Latest Desktop Client

1. Visit the official Feishin GitHub repository releases page.
2. Locate the latest release version
3. Download the appropriate file for your system architecture (typically Feishin-x.x.x-linux-x86_64.AppImage for most systems)

Making the File Executable

After downloading, you need to make the file executable:

cd ~/Downloads
chmod +x Feishin-*.AppImage

First-Time Setup

Run the Feishin AppImage:

./Feishin-*.AppImage

During the first launch, Feishin will prompt you to locate the MPV binary. Enter the path (typically /usr/bin/mpv on Debian 12) and click “Save.”

Creating Desktop Integration

For easier access, create a desktop shortcut:

mkdir -p ~/.local/share/applications

Create a new file named feishin.desktop:

nano ~/.local/share/applications/feishin.desktop

Add the following content (adjust paths accordingly):

[Desktop Entry]
Name=Feishin
Comment=Modern self-hosted music player
Exec=/path/to/Feishin-x.x.x-linux-x86_64.AppImage
Icon=/path/to/feishin.png
Terminal=false
Type=Application
Categories=Audio;Music;Player;AudioVideo;

You can extract the application icon with:

./Feishin-*.AppImage --appimage-extract
cp squashfs-root/usr/share/icons/hicolor/512x512/apps/feishin.png ~/.local/share/icons/

Then update the Icon path in your desktop file to point to ~/.local/share/icons/feishin.png.

The desktop client installation provides full access to Feishin’s features, including both MPV and web player backends, making it ideal for daily use on Debian 12.

Method 2: Running Feishin as an AppImage

The AppImage installation provides a portable, self-contained version of Feishin that runs without impacting your system’s package management. This method is particularly useful for testing or when you want to avoid potential package conflicts.

Downloading the AppImage

1. Navigate to the Feishin releases page on GitHub
2. Download the latest AppImage file for your architecture (typically x86_64 for most systems)
3. Save the file to a convenient location, such as your Downloads folder or a dedicated Applications directory

Making the AppImage Executable

Open a terminal and navigate to the directory containing the downloaded AppImage:

cd ~/Downloads
chmod +x Feishin-*.AppImage

Running the AppImage

Execute the AppImage directly:

./Feishin-*.AppImage

On first run, you’ll need to configure the path to your MPV binary as described in the previous section.

Creating a Permanent Location

For long-term use, consider moving the AppImage to a dedicated directory:

mkdir -p ~/Applications
mv ~/Downloads/Feishin-*.AppImage ~/Applications/

Automating Updates

The AppImage format requires manual updates. To update:

1. Download the latest AppImage
2. Replace the existing file
3. Ensure execution permissions are set

For convenient updates, consider creating a symbolic link:

ln -sf ~/Applications/Feishin-exact-version.AppImage ~/Applications/feishin.AppImage

When updating, you only need to replace the target file without changing your shortcuts.

AppImage installation offers excellent portability and eliminates dependency concerns, making it a solid choice for many Debian 12 users.

Method 3: Setting Up Feishin with Docker on Debian 12

Docker provides an isolated environment for running Feishin, ensuring consistency across different systems and simplifying management. This method is ideal for server environments or users who prefer containerized applications.

Installing Docker on Debian 12

First, install Docker if it’s not already on your system:

# Update package index and install prerequisites
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg lsb-release -y

# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set up Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

# Add your user to the Docker group (optional, for running Docker without sudo)
sudo usermod -aG docker $USER

Log out and back in for the group changes to take effect.

Setting Up Docker Compose

Create a new directory for your Feishin Docker setup:

mkdir -p ~/docker/feishin
cd ~/docker/feishin

Create a Docker Compose file:

nano docker-compose.yml

Add the following content:

version: '3'
services:
  feishin:
    image: ghcr.io/jeffvli/feishin:latest
    container_name: feishin
    ports:
      - "3000:3000"
    restart: unless-stopped
    environment:
      - PUBLIC_PATH=/
    volumes:
      - ./config:/app/config

Running the Docker Container

Start the Feishin container:

docker-compose up -d

Access Feishin through your web browser at http://localhost:3000.

Environment Variable Configuration

Customize Feishin’s behavior with environment variables in your docker-compose.yml:

• PUBLIC_PATH: Define a subpath if not hosting at root
• SERVER_NAME: Pre-configure server name
• SERVER_TYPE: Specify server type (jellyfin or navidrome)
• SERVER_URL: Define server URL
• SERVER_LOCK: Prevent users from changing server settings

For example, to lock to a specific Navidrome server:

environment:
  - PUBLIC_PATH=/
  - SERVER_NAME=MyNavidrome
  - SERVER_TYPE=navidrome
  - SERVER_URL=https://navidrome.example.com
  - SERVER_LOCK=true

Updating the Docker Image

To update Feishin to the latest version:

docker-compose pull
docker-compose up -d

Docker installation provides excellent isolation and simplified management, though it only supports the web player backend, not MPV.

Configuring MPV for Feishin

Configuring MPV properly is crucial for optimal audio playback in Feishin. This section covers essential MPV setup steps and optimization options.

Setting the MPV Binary Path

When you first run Feishin, you’ll be prompted to specify the path to your MPV binary. On Debian 12, this is typically located at:

/usr/bin/mpv

If you’re unsure, you can find it using:

which mpv

MPV Configuration Options

For advanced customization, you can modify MPV’s configuration file:

mkdir -p ~/.config/mpv
nano ~/.config/mpv/mpv.conf

Add these optimization options for music playback:

# Audio optimization settings
audio-buffer=4
audio-samplerate=48000
audio-channels=2
audio-format=float

# Performance settings
vo=gpu
hwdec=auto

Optimizing MPV for Music Playback

For the best music experience, consider these additional settings:

# Music-specific optimizations
audio-display=no
video=no
gapless-audio=yes

Troubleshooting MPV Integration

If you encounter issues with MPV playback:

1. Verify MPV works independently by playing an audio file:

   mpv --no-video /path/to/audio/file.mp3

2. Check MPV permissions:

   ls -l /usr/bin/mpv

   The output should show executable permissions.

3. Install additional codecs if needed:

   sudo apt install gstreamer1.0-plugins-{base,good,bad,ugly} -y

4. Enable verbose logging in Feishin to identify specific MPV issues.

Proper MPV configuration significantly enhances Feishin’s playback quality and performance on Debian 12. The web player provides an alternative if MPV issues persist, though many users report that MPV offers superior performance and reliability.

Connecting Feishin to Your Music Server

Feishin requires a connection to a compatible music server to access your collection. This section guides you through setting up connections to popular servers like Jellyfin and Navidrome.

Adding a Server Connection

1. Launch Feishin and click the “Open menu” button
2. Select “Manage servers” from the dropdown
3. In the dialog that appears, click the “Add server” button

Setting Up Jellyfin Connection

For Jellyfin servers, enter:

• Server Name: Choose a descriptive name
• Server Type: Select “Jellyfin” from the dropdown
• Server URL: Enter the complete URL, including protocol and port (e.g., http://192.168.1.100:8096)
• Username: Your Jellyfin username
• Password: Your Jellyfin password
• Save password: Recommended for convenience

Setting Up Navidrome Connection

For Navidrome servers:

• Server Name: Choose a descriptive name
• Server Type: Select “Navidrome” from the dropdown
• Server URL: Enter the complete URL (e.g., https://navidrome.example.com)
• Username: Your Navidrome username
• Password: Your Navidrome password
• Save password: Recommended for convenience

Password Storage on Debian

On Debian 12, Feishin uses libsecret for password storage by default. Alternative options include:

• kwallet4
• kwallet5
• kwallet6

To change the password store, navigate to Settings > Window > Passwords/secret score.

Optimizing Navidrome for Feishin

For better experience with Navidrome servers, modify the SessionTimeout setting in your Navidrome configuration:

SessionTimeout = "72h"

This extends session duration and reduces authentication frequency.

Testing Your Connection

After adding a server, test the connection by:

1. Browsing your music library in Feishin
2. Playing a track to verify audio playback
3. Checking that album art and metadata display correctly

If you encounter connection issues, verify that:

• Server URL is correct and includes protocol and port
• Server is accessible from your network
• Authentication credentials are accurate
• Any firewalls allow the necessary connections

With your server successfully connected, Feishin will display your music library, allowing you to browse and play your collection.

Advanced Configuration and Options

Feishin offers numerous advanced configuration options that allow you to tailor the experience to your preferences. This section covers key customization areas to enhance your Debian 12 installation.

Customizing the User Interface

Feishin’s interface can be personalized through the Settings menu:

• Theme selection: Choose between light and dark themes
• Layout options: Customize sidebar visibility and position
• Grid view settings: Adjust album art size and information display
• Font settings: Modify text appearance throughout the application

Setting Up Lyrics Support

Configure lyrics display for your music:

1. Navigate to Settings > Player > Lyrics
2. Enable synchronized or unsynchronized lyrics
3. Configure lyrics fetch sources and display options
4. Adjust lyrics display position and appearance

Configuring Scrobbling

Track your listening history:

1. Go to Settings > Player > Scrobbling
2. Enable scrobbling to your server
3. Configure minimum listen time and thresholds
4. Set up automatic scrobbling options

Smart Playlist Configuration

For Navidrome users, configure smart playlists:

1. Navigate to the Playlists section
2. Select “Create smart playlist”
3. Define rules and conditions for automatic playlist generation
4. Save and configure update frequency

Audio Output Configuration

Fine-tune audio playback:

1. Go to Settings > Player > Audio
2. Select preferred audio device
3. Configure normalization settings
4. Adjust equalizer settings if available
5. Set crossfade options between tracks

Keyboard Shortcuts Customization

Optimize your workflow with custom shortcuts:

1. Navigate to Settings > Window > Keyboard shortcuts
2. Review existing shortcuts
3. Modify shortcuts for common actions
4. Create new shortcuts for frequently used functions

These advanced configurations allow you to create a personalized Feishin experience optimized for your specific needs and preferences on your Debian 12 system.

Security Considerations

Securing your Feishin installation is important, especially if you plan to access it remotely. This section covers essential security practices for your Debian 12 setup.

Securing Password Storage

Feishin stores server credentials securely using libsecret on Debian 12. Enhance password security by:

1. Using strong, unique passwords for your music servers
2. Configuring alternative credential storage if needed through Settings > Window
3. Limiting automatic login on shared computers

Network Security Configuration

If exposing Feishin to networks beyond your local environment:

1. Use a reverse proxy like Apache or Nginx
2. Implement SSL/TLS encryption
3. Configure firewall rules using UFW:

   sudo apt install ufw
   sudo ufw allow ssh
   sudo ufw allow http
   sudo ufw allow https
   sudo ufw enable

Filesystem Permissions

Ensure proper permissions for Feishin files:

1. Restrict AppImage or installation files to your user account
2. Apply appropriate permissions to configuration directories
3. Limit access to cached media files

SSL/TLS Setup

For secure remote access:

1. Install Certbot for Let’s Encrypt certificates
2. Configure SSL/TLS in your reverse proxy
3. Enable HTTPS-only access
4. Implement HTTP Strict Transport Security (HSTS)

Regular Updates

Maintaining security requires consistent updates:

1. Monitor the Feishin GitHub repository for new releases
2. Apply updates promptly when available
3. Subscribe to security notifications for dependencies like MPV

Following these security practices helps protect your music collection and account credentials while using Feishin on Debian 12.

Troubleshooting Common Issues on Debian 12

Even with careful installation and configuration, issues may arise with Feishin on Debian 12. This section addresses frequent problems and their solutions.

Playback Issues

If songs won’t play or stop unexpectedly:

1. Automatic Song Progression Problems:
   • Switch from web player to MPV backend, as many users report this resolves issues with songs not automatically progressing
   • The issue is known particularly on Debian 12, where MPV works much more reliably than the web player
2. Audio Stuttering:
   • Increase buffer size in MPV configuration
   • Reduce system load by closing unnecessary applications
   • Check network stability if streaming from remote servers
3. No Sound Output:
   • Verify system volume and mute settings
   • Confirm correct audio device selection
   • Test MPV independently: mpv --no-video /path/to/audio/file.mp3

Connection Issues

For problems connecting to your music server:

1. Server Authentication Errors:
   • Verify credentials are correct
   • Check server logs for authentication failures
   • Ensure server is reachable: ping server_address
2. Intermittent Connectivity:
   • Inspect network stability
   • Increase connection timeouts
   • Check server resource utilization
3. SSL Certificate Problems:
   • Verify certificate validity
   • Add self-signed certificates to trusted store
   • Test with HTTP temporarily to isolate certificate issues

Library Scanning Problems

If your library doesn’t appear or update:

1. Missing Albums or Tracks:
   • Verify library scan completed on server
   • Check file permissions on media files
   • Ensure proper metadata is present
2. Slow Library Loading:
   • Optimize server database
   • Reduce artworks quality in settings
   • Implement pagination for large collections

Application Crashes

For stability issues:

1. Startup Failures:
   • Check logs at ~/.config/Feishin/logs
   • Verify MPV installation and permissions
   • Temporarily rename configuration directory to reset settings
2. Memory Usage Problems:
   • Monitor memory usage during extended sessions
   • Restart application periodically
   • Reduce cache size in advanced settings

Most issues with Feishin on Debian 12 can be resolved by switching from the web player to MPV backend, ensuring proper configuration, and verifying connectivity to your music server.

Enhancing Your Feishin Experience

Take your Feishin installation to the next level with these enhancements and optimizations for your Debian 12 system.

Performance Optimization

Improve Feishin’s responsiveness:

1. Memory Management:
   • Adjust cache sizes in Settings > Advanced
   • Limit simultaneous background processes
   • Set appropriate quality levels for your hardware
2. Startup Optimization:
   • Configure autostart options
   • Minimize server connections at startup
   • Disable unused features

Integration with Other Services

Extend Feishin’s capabilities:

1. Music Information Services:
   • Configure metadata sources
   • Enable artist information display
   • Set up album review integration
2. Mobile Synchronization:
   • Use companion apps that connect to the same server
   • Synchronize playlists across devices
   • Configure mobile-specific quality settings

Power User Features

Leverage advanced capabilities:

1. Keyboard Navigation:
   • Learn and customize keyboard shortcuts
   • Create macros for common actions
   • Implement global media key support
2. Custom View Configurations:
   • Create specialized views for different genres
   • Set up contextual display options
   • Configure column layouts for detailed information

Library Management Best Practices

Optimize how Feishin interacts with your collection:

1. Metadata Organization:
   • Ensure consistent tagging on your server
   • Use folder structure that Feishin navigates efficiently
   • Implement artwork management best practices
2. Playlist Strategy:
   • Create smart playlists for dynamic content
   • Organize static playlists by context or mood
   • Develop rating systems for personal recommendations

These enhancements help you get the most from your Feishin installation on Debian 12, creating a seamless and enjoyable music listening experience tailored to your preferences.

Congratulations! You have successfully installed Feishin. Thanks for using this tutorial for installing the Feishin modern self-hosted music player on Debian 12 “Bookworm” system. For additional help or useful information, we recommend you check the official Feishin website.