# ๐ŸŽต Songloft Quick Start Guide

็ฎ€ไฝ“ไธญๆ–‡ โ€ข English

Songloft

[![GitHub License](https://img.shields.io/github/license/songloft-org/songloft)](https://github.com/songloft-org/songloft) [![Docker Image Version](https://img.shields.io/docker/v/songloft/songloft?sort=semver&label=docker%20image)](https://hub.docker.com/r/songloft/songloft) [![Docker Pulls](https://img.shields.io/docker/pulls/songloft/songloft)](https://hub.docker.com/r/songloft/songloft) [![GitHub Release](https://img.shields.io/github/v/release/songloft-org/songloft)](https://github.com/songloft-org/songloft/releases) [![Visitors](https://api.visitorbadge.io/api/daily?path=songloft-org%2Fsongloft&label=daily%20visitor&countColor=%232ccce4&style=flat)](https://visitorbadge.io/status?path=songloft-org%2Fsongloft) [![Visitors](https://api.visitorbadge.io/api/visitors?path=songloft-org%2Fsongloft&label=total%20visitor&countColor=%232ccce4&style=flat)](https://visitorbadge.io/status?path=songloft-org%2Fsongloft)

๐ŸŽต A self-hosted music server for personal use โ€” manage only the music you legally own

> ๐Ÿ“ฃ **About the rename**: As of v2.0, this project has been renamed from **MiMusic** to **Songloft** (the core and features remain unchanged โ€” this is only a brand upgrade). The old `mimusic-org` GitHub organization and the `hanxi/mimusic` Docker image will be kept as redirects for at least one year but will no longer be updated. See the [GitHub Releases](https://github.com/songloft-org/songloft/releases) for details.

๐Ÿ  GitHub โ€ข ๐Ÿ“ฅ Downloads โ€ข ๐Ÿ“– Docs โ€ข ๐Ÿ’ฌ Issues โ€ข ๐Ÿ‘ฅ WeChat Group โ€ข ๐Ÿ“ธ Screenshots

> ### ๐Ÿ’š A labor of love ยท Beware of scams > > Songloft is a **fully free** open-source project, built purely out of passion โ€” with no commercial interest whatsoever: > > - โœ… **Free forever** โ€”โ€” no paid features, in-app purchases, or subscriptions > - โœ… **No ads** โ€”โ€” no advertising or commercial promotion of any kind > - โœ… **No sponsorship / donations** โ€”โ€” there is no payment channel at all > - โš ๏ธ **Beware of scams** โ€”โ€” the only official channels are the [GitHub repository](https://github.com/songloft-org/songloft), the [docs site](https://songloft.hanxi.cc), and the [official WeChat group](https://github.com/songloft-org/songloft/issues/2). Anyone charging fees, selling "paid versions", offering paid deployment, or soliciting donations in Songloft's name is unrelated to this project; we never charge anyone, not even inside the group. Please stay alert to scams. ## โœจ Core Features - ๐ŸŽต **Local music management** โ€” Scans local directories and automatically extracts covers and metadata from MP3/FLAC/WAV/APE/OGG/Opus/M4A/M4B/WMA/AIF/AIFF/MKA and other formats - ๐ŸŽฌ **Video support** โ€” Scans video containers such as MP4/MOV/M4V/MKV/WebM/AVI/TS/MPG/MPEG/FLV/WMV/RM/RMVB/3GP, detects real video tracks, and renders the picture in-app - ๐Ÿงฉ **JS plugin system** โ€” Runs on a QuickJS sandbox with a permission model, health checks, and hot reload; freely extend audio sources / metadata / device control and more - ๐Ÿ“ฑ **Cross-platform clients** โ€” The Flutter client supports six platforms: Android, iOS, macOS, Windows, Linux, and Web - ๐Ÿ“ฆ **Bundle local mode** โ€” The client embeds the Go backend, so no server deployment is needed โ€” play your local music directly on your phone or computer - ๐Ÿ“บ **Kodi plugin client** โ€” Supports big-screen devices like Xbox, Apple TV, Raspberry Pi, and Android TV, optimized for remote control operation for a smooth living-room media experience - ๐ŸŒ **Web interface** โ€” The full edition ships with a built-in web frontend that works out of the box - ๐Ÿ”‘ **JWT authentication** โ€” Dual-token mechanism (Access Token + Refresh Token) with multi-device management - ๐Ÿ“ก **Network songs & radio** โ€” Add network audio URLs and radio streams, transparently cached to the server during playback - ๐Ÿ”Œ **Full REST API** โ€” Built-in Swagger documentation for easy integration and further development - โšก **Lightweight and efficient** โ€” Written in Go, CGO-free, with no external dependencies โ€” ideal for low-power devices like NAS and Raspberry Pi ## ๐Ÿ–ผ๏ธ Screenshots

Home ยท Desktop

Immersive Player ยท Mobile

> ๐Ÿ“ธ More screens (library, playlists, settings, etc. โ€” desktop / mobile with light / dark themes) are in the **[Screenshot Gallery](docs/en/screenshots.md)**. ## โš–๏ธ Copyright and Disclaimer Songloft is a **self-hosted tool for personal use**, designed to help users manage the music files they legally own. Before using this project, please be sure to read and understand the following terms: - ๐Ÿšซ **No music content provided** โ€” Songloft itself does not bundle, distribute, or store any copyrighted music resources. It is merely open-source software for managing your local music library - โœ… **Manage only music from legitimate sources** โ€” Users should use Songloft only to manage music files they have legally obtained, including but not limited to: - Digital music purchased and downloaded by yourself - Personal backups ripped from physical records - Works you created or recorded yourself - Public Domain works - Works explicitly licensed under open licenses such as CC (Creative Commons) - ๐Ÿ”Œ **Third-party plugin disclaimer** โ€” JS plugins are maintained by the third-party community. **The main repository does not bundle or distribute any finished third-party audio-source plugins**. The copyright of any network audio sources, metadata, or lyrics accessed by plugins belongs to their respective rights holders. **When using features such as network audio sources, users must bear responsibility for copyright compliance themselves** and comply with the laws and regulations of their country/region - ๐Ÿ  **For personal, non-commercial use only** โ€” Using this project for commercial purposes, publicly distributing copyrighted content, or building public services aimed at an unspecified general audience is strictly prohibited - โš ๏ธ **Use at your own risk** โ€” Any legal liability, disputes, or losses arising from improper use of this project (including but not limited to infringement of third-party copyrights) are borne solely by the user. The authors and contributors of this project assume no responsibility - ๐Ÿ“ฉ **Infringement reports** โ€” If you are a copyright holder and believe that this project's code, documentation, or officially distributed plugins infringe your legitimate rights, please contact us via [GitHub Issues](https://github.com/songloft-org/songloft/issues) or email (im.hanxi@gmail.com), and we will handle it promptly after verification. For infringement issues concerning third-party community plugins, please contact the maintainer of that plugin directly - โ„ข๏ธ **Trademark notice** โ€” All brands, protocols, and product names mentioned in this project and its built-in plugins (including but not limited to "MIoT", "Bluetooth", "Android", "iOS", "macOS", "Windows", "Docker", etc.) belong to their respective trademark owners. These names appear solely for interoperability and nominative fair use purposes. **Songloft is not affiliated with the aforementioned trademark holders, nor has it received any form of authorization or endorsement from them**. See [NOTICE](./NOTICE) for details - ๐Ÿ”’ **Privacy** โ€” The Songloft server **includes no telemetry whatsoever**; all data is stored locally on your own machine. See [PRIVACY.md](./PRIVACY.md) for details > ๐Ÿ’ก We respect and support intellectual property protection. If you enjoy an artist's work, please purchase or subscribe through official channels to support the creators. ## ๐Ÿ“‹ Editions Songloft offers three editions to suit different scenarios: | Edition | Suffix | Description | Best for | |------|------|------|----------| | ๐ŸŒŸ **Full** | none | Includes the web frontend, works out of the box | Recommended for first-time users โ€” just open the service address to see the web interface | | ๐Ÿ“ฆ **Lite** | `-lite` | Does not include the web frontend, smaller in size | Pairing with the Flutter desktop/mobile client, or decoupled frontend/backend deployment | | ๐Ÿ“ฑ **Bundle** | `bundled-` | Flutter client with the Go backend embedded | No server deployment needed โ€” play local music directly on your phone or computer | > ๐Ÿ’ก **Recommendation**: For first-time use, download the default **Full** edition โ€” it works out of the box with no extra frontend configuration. > Want to use it standalone on your phone or computer without deploying a server? Download the **Bundle** edition. ## ๐Ÿ–ฅ๏ธ Platform Support ### ๐Ÿ“ฆ Binaries #### ๐ŸŒŸ Full Edition (Recommended) Includes the web frontend, works out of the box: | Platform | Architecture | Download | |------|------|--------| | ๐Ÿง Linux | x86_64 | [songloft-linux-amd64](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-amd64) | | ๐Ÿง Linux | ARM64 | [songloft-linux-arm64](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-arm64) | | ๐Ÿง Linux | ARMv7 | [songloft-linux-armv7](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-armv7) | | ๐ŸŽ macOS | x86_64 (Intel) | [songloft-darwin-amd64](https://github.com/songloft-org/songloft/releases/latest/download/songloft-darwin-amd64) | | ๐ŸŽ macOS | ARM64 (Apple Silicon) | [songloft-darwin-arm64](https://github.com/songloft-org/songloft/releases/latest/download/songloft-darwin-arm64) | | ๐ŸชŸ Windows | x86_64 | [songloft-windows-amd64.exe](https://github.com/songloft-org/songloft/releases/latest/download/songloft-windows-amd64.exe) | | ๐ŸชŸ Windows | ARM64 | [songloft-windows-arm64.exe](https://github.com/songloft-org/songloft/releases/latest/download/songloft-windows-arm64.exe) | #### ๐Ÿ“ฆ Lite Edition Does not include the web frontend, smaller in size: | Platform | Architecture | Download | |------|------|--------| | ๐Ÿง Linux | x86_64 | [songloft-linux-amd64-lite](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-amd64-lite) | | ๐Ÿง Linux | ARM64 | [songloft-linux-arm64-lite](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-arm64-lite) | | ๐Ÿง Linux | ARMv7 | [songloft-linux-armv7-lite](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-armv7-lite) | | ๐ŸŽ macOS | x86_64 (Intel) | [songloft-darwin-amd64-lite](https://github.com/songloft-org/songloft/releases/latest/download/songloft-darwin-amd64-lite) | | ๐ŸŽ macOS | ARM64 (Apple Silicon) | [songloft-darwin-arm64-lite](https://github.com/songloft-org/songloft/releases/latest/download/songloft-darwin-arm64-lite) | | ๐ŸชŸ Windows | x86_64 | [songloft-windows-amd64-lite.exe](https://github.com/songloft-org/songloft/releases/latest/download/songloft-windows-amd64-lite.exe) | | ๐ŸชŸ Windows | ARM64 | [songloft-windows-arm64-lite.exe](https://github.com/songloft-org/songloft/releases/latest/download/songloft-windows-arm64-lite.exe) | #### ๐Ÿ“ฑ Bundle Edition (Embedded Backend, No Server Required) The client embeds the Go backend โ€” on first launch, click "Use local mode" and select a music directory to get started: | Platform | Architecture | Download | |------|------|--------| | ๐Ÿค– Android | ARM64 + ARMv7 | [songloft-bundled-android-arm64-v8a.apk](https://github.com/songloft-org/songloft/releases/latest/download/songloft-bundled-android-arm64-v8a.apk) | | ๐Ÿง Linux | x86_64 | [songloft-bundled-linux-x64.tar.gz](https://github.com/songloft-org/songloft/releases/latest/download/songloft-bundled-linux-x64.tar.gz) | | ๐ŸŽ macOS | ARM64 (Apple Silicon) | [songloft-bundled-macos-arm64.dmg](https://github.com/songloft-org/songloft/releases/latest/download/songloft-bundled-macos-arm64.dmg) | | ๐ŸชŸ Windows | x86_64 | [songloft-bundled-windows-x64.zip](https://github.com/songloft-org/songloft/releases/latest/download/songloft-bundled-windows-x64.zip) | | ๐ŸŽ iOS | ARM64 | [songloft-bundled-ios-arm64.ipa](https://github.com/songloft-org/songloft/releases/latest/download/songloft-bundled-ios-arm64.ipa) | ### ๐Ÿณ Docker Images #### ๐ŸŒŸ Full Edition (Recommended) | Platform | Download | |------|--------| | ๐Ÿง Linux x86_64 | [songloft-docker-linux-amd64.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-amd64.tar) | | ๐Ÿง Linux ARM64 | [songloft-docker-linux-arm64.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-arm64.tar) | | ๐Ÿง Linux ARMv7 | [songloft-docker-linux-arm-v7.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-arm-v7.tar) | #### ๐Ÿ“ฆ Lite Edition | Platform | Download | |------|--------| | ๐Ÿง Linux x86_64 | [songloft-docker-linux-amd64-lite.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-amd64-lite.tar) | | ๐Ÿง Linux ARM64 | [songloft-docker-linux-arm64-lite.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-arm64-lite.tar) | | ๐Ÿง Linux ARMv7 | [songloft-docker-linux-arm-v7-lite.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-arm-v7-lite.tar) | ### ๐Ÿ“ฑ Flutter Client Beyond the web interface, Songloft also offers a more powerful cross-platform Flutter client that supports background playback, local caching, media controls (headphones/lock screen/notification bar), and other capabilities the server web interface cannot provide โ€” covering all six platforms: iOS, Android, macOS, Windows, Linux, and Web. ๐Ÿ”— **GitHub repository**: [songloft-org/songloft-player](https://github.com/songloft-org/songloft-player) - **Standard edition** (requires connecting to a server): [songloft-player Releases](https://github.com/songloft-org/songloft-player/releases/latest) - **Bundle edition** (embedded backend, no server required): [songloft Releases](https://github.com/songloft-org/songloft/releases/latest) (download the `songloft-bundled-*` files) > ๐ŸชŸ **Windows users**: install & update the Flutter client in one line via [Scoop](https://scoop.sh): > ```powershell > scoop bucket add songloft https://github.com/songloft-org/songloft-scoop > scoop install songloft-player > # Update: scoop update songloft-player > # Uninstall: scoop uninstall songloft-player (add --purge to also remove config data) > ``` > ๐Ÿ’ก **How to use the Bundle edition**: On first launch, tap "Use local mode" on the login page โ†’ select a music directory โ†’ done automatically. You can switch between local/remote mode at any time from the settings page. > ๐Ÿ’ก When using the **Lite (-lite)** server, we recommend pairing it directly with the Flutter client (no need to deploy a separate web frontend). If you do need a standalone web frontend, refer to the `flutter build web` process in the [songloft-player](https://github.com/songloft-org/songloft-player) repository to build it yourself and serve the static files via a reverse proxy such as Nginx. ### ๐Ÿ“บ TV Client In addition to the Flutter client, for TV we recommend the dedicated **[songloft-tv](https://github.com/boluofan/songloft-tv)** client, designed specifically for Android TV with remote control support. ### ๐Ÿ“บ Kodi Plugin In addition to the Flutter client, Songloft also provides an official **Kodi plugin** that lets you play your Songloft music library directly in the Kodi media center. It's ideal for Kodi-capable big-screen devices such as **Xbox**, Apple TV, Raspberry Pi, and Android TV, optimized for remote control operation for a smooth living-room media experience. ๐Ÿ”— **GitHub repository**: [songloft-org/plugin.audio.songloft](https://github.com/songloft-org/plugin.audio.songloft) ๐Ÿ“ฅ **Download**: [GitHub Releases](https://github.com/songloft-org/plugin.audio.songloft/releases/latest) ## ๐Ÿš€ Quick Start > ๐Ÿ” **Security notice (must read)**: The default admin account is `admin / admin`, which is **suitable for local testing only**. For any deployment exposed to the internet or accessed by multiple devices, be sure to set a strong password via the `ADMIN_USERNAME` / `ADMIN_PASSWORD` environment variables before starting; otherwise your music library may be accessible to strangers. ### ๐Ÿ“ฆ Option 1: Run the Binary Directly #### ๐Ÿง Linux / ๐ŸŽ macOS ```bash # 1๏ธโƒฃ Download the binary for your platform (the default is the full edition) # For example, Linux x86_64: wget https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-amd64 mv songloft-linux-amd64 songloft # 2๏ธโƒฃ Add execute permission chmod +x songloft # 3๏ธโƒฃ Create the required directories mkdir -p music data # 4๏ธโƒฃ Start (recommended to pass credentials via environment variables to keep them out of shell history / process list) ADMIN_USERNAME=admin ADMIN_PASSWORD='your_strong_password' ./songloft ``` > ๐ŸŽ **Note for macOS users**: Binaries downloaded from GitHub carry the Gatekeeper quarantine attribute and will be blocked on first run. Before running, execute: > ```bash > xattr -d com.apple.quarantine ./songloft > ``` #### ๐ŸชŸ Windows ```powershell # 1๏ธโƒฃ Download the binary for your platform (the default is the full edition) and rename it to songloft.exe # For example, Windows x86_64: songloft-windows-amd64.exe # 2๏ธโƒฃ Create the required directories mkdir music mkdir data # 3๏ธโƒฃ Set environment variables and start (PowerShell) $env:ADMIN_USERNAME = "admin" $env:ADMIN_PASSWORD = "your_strong_password" .\songloft.exe ``` ### ๐Ÿณ Option 2: Docker Deployment #### ๐ŸŒ Pull from Docker Hub (Recommended) ```bash # ๐ŸŒŸ Full edition (recommended, includes the web frontend; :latest is the full edition) docker pull songloft/songloft:latest # ๐Ÿ“ฆ Lite edition (no web frontend, must be paired with the Flutter client) docker pull songloft/songloft:lite # Run the container docker run -d \ --name songloft \ -p 58091:58091 \ -v /path/to/music:/app/music \ -v /path/to/data:/app/data \ -e ADMIN_USERNAME=admin \ -e ADMIN_PASSWORD='your_strong_password' \ songloft/songloft:latest ``` #### ๐Ÿ“ฅ Import the Image Offline from a Release Suitable for environments that cannot access Docker Hub directly: ```bash # 1๏ธโƒฃ Download the Docker image tar file for your platform (the default is the full edition) wget https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-amd64.tar # 2๏ธโƒฃ Import the image docker load -i songloft-docker-linux-amd64.tar # 3๏ธโƒฃ List the imported image tags docker images | grep songloft # 4๏ธโƒฃ Start it with the docker run command from the previous section (remember to replace with the imported image tag) ``` #### ๐Ÿ™ Docker Compose Deployment (Recommended) Using Docker Compose makes it easier to manage container configuration: ```yaml version: '3.8' services: songloft: image: songloft/songloft:latest container_name: songloft restart: always ports: - "58091:58091" volumes: - /path/to/music:/app/music - /path/to/data:/app/data environment: - ADMIN_USERNAME=admin - ADMIN_PASSWORD=your_strong_password - LISTEN_PORT=58091 ``` Save the above as a `docker-compose.yml` file, then run: ```bash # Start the service docker-compose up -d # View logs docker-compose logs -f # Stop the service docker-compose down ``` ### ๐Ÿ  Method 3: Home Assistant Add-on If you run Home Assistant OS (HAOS), you can install Songloft as an **add-on** with one click โ€” no manual `docker run` required. [![Add repository to your Home Assistant.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fsongloft-org%2Fhome-assistant-addon) Clicking the badge above opens the "Add add-on repository" dialog in your own Home Assistant; or do it manually: 1. Go to **Settings โ†’ Add-ons โ†’ Add-on Store**, open the top-right menu **Repositories**, and add: `https://github.com/songloft-org/home-assistant-addon` 2. After refreshing, find **Songloft** in the store and install it 3. On the **Configuration** tab, set the admin username/password and music library path (defaults to `/media`), then start 4. Use the **Open Web UI** button on the add-on page to access it Put your music in Home Assistant's media folder (`/media`) or share folder (`/share`) to have it scanned. Data is persisted in the add-on's `/data` directory and survives reinstalls. > ๐Ÿ” **Security**: the default `admin/admin` credentials are for local testing only. Set a strong password on the Configuration tab before exposing this instance. ## ๐Ÿ“‹ Usage Flow ### 1๏ธโƒฃ Start the Service Once the service is running, visit `http://localhost:58091` to open the web interface (built in only in the full edition; for the lite edition, please use the [Flutter client](#-flutter-client) to connect). ### 2๏ธโƒฃ Log In Log in with the configured admin username and password. ### 3๏ธโƒฃ Configure the Music Directory After your first login, go to the "Settings" page to configure the music file directory (`music_path`). For Docker deployments, this is usually set to `/app/music`. ### 4๏ธโƒฃ Scan for Music In the web interface, click the "Scan" button, and the system will automatically scan the audio files in the music directory and extract their metadata. ### 5๏ธโƒฃ Play Music Once the scan is complete, you can browse and play music in the interface. ## โš™๏ธ Configuration Songloft relies on only a few startup-time settings (credentials, port, database path) specified via environment variables or command-line arguments. All other business configuration (music directory, scan rules, cover storage, etc.) is stored in the database `config` table and managed through the web interface after startup. ### ๐ŸŒ Environment Variables | Variable | Description | Default | |--------|------|--------| | `ADMIN_USERNAME` | ๐Ÿ‘ค Admin username | admin | | `ADMIN_PASSWORD` | ๐Ÿ” Admin password | admin | | `LISTEN_PORT` | ๐Ÿ”Œ Service port | 58091 | | `DB_PATH` | ๐Ÿ’พ Database file path | data/songloft.db | | `BASE_PATH` | ๐Ÿ”— URL base path (for reverse-proxy subpath deployment, e.g. `/songloft`) | empty (root path) | | `MUSIC_DIR` | ๐ŸŽต Music directory (overrides the database default when non-empty; equivalent to `-music`) | empty | > ๐Ÿ“ In the Docker image, the music directory and data directory default to `/app/music` and `/app/data` โ€” just mount them with `-v`; to point elsewhere, use `MUSIC_DIR` to set the music directory. ### ๐Ÿ’ป Command-Line Arguments ```bash # View help ./songloft -help # Specify the port ./songloft -port 8080 # Specify the database file path ./songloft -db data/songloft.db # Specify the admin account (not recommended โ€” the password appears in shell history and the ps process list) ./songloft -username admin -password your_password # Specify a subpath (used for reverse-proxy deployment) ./songloft -base-path /songloft ``` > โš™๏ธ **Priority**: Command-line arguments **take precedence over** environment variables. If neither is provided, it falls back to the defaults (admin account `admin/admin`). > โš ๏ธ **Argument format**: Songloft uses single-dash arguments (e.g. `-help`) and does not support double-dash arguments (e.g. `--help`). > ๐Ÿ” **Password security**: We recommend passing the password via the `ADMIN_PASSWORD` environment variable to avoid `-password` being exposed in plaintext in the process list. ## ๐ŸŒ Reverse-Proxy Subpath Deployment If you mount Songloft under a subpath via a reverse proxy such as Nginx (e.g. `https://nas.example.com/songloft/`), you need to configure the `BASE_PATH` environment variable. ### Configuration Steps **1. Specify BASE_PATH when starting Songloft:** ```bash # Environment variable BASE_PATH=/songloft ./songloft # Or command-line argument ./songloft -base-path /songloft # Docker docker run -d \ --name songloft \ -p 58091:58091 \ -v /path/to/music:/app/music \ -v /path/to/data:/app/data \ -e ADMIN_USERNAME=admin \ -e ADMIN_PASSWORD='your_strong_password' \ -e BASE_PATH=/songloft \ songloft/songloft:latest ``` **2. Configure the Nginx reverse proxy:** ```nginx location /songloft/ { proxy_pass http://127.0.0.1:58091; proxy_read_timeout 52w; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } ``` > โš ๏ธ **Note**: Do **not** add a trailing slash to `proxy_pass`. Nginx forwards the full path (including `/songloft/`) to the backend, and Songloft handles stripping the prefix itself. ### Client Connection | Client type | Server address to enter | |-----------|--------------| | Built-in web frontend | Simply visit `https://nas.example.com/songloft/` in the browser โ€” it works automatically | | Flutter desktop/mobile client | Enter `https://nas.example.com/songloft` | ### Docker Compose Example ```yaml version: '3.8' services: songloft: image: songloft/songloft:latest container_name: songloft restart: always ports: - "58091:58091" volumes: - /path/to/music:/app/music - /path/to/data:/app/data environment: - ADMIN_USERNAME=admin - ADMIN_PASSWORD=your_strong_password - BASE_PATH=/songloft ``` ## ๐Ÿ’ป System Requirements | Item | Requirement | |------|------| | **Operating system** | ๐Ÿง Linux / ๐ŸŽ macOS / ๐ŸชŸ Windows | | **Architecture** | x86_64 / ARM64 / ARMv7 | | **Optional dependency** | ๐Ÿ”ง ffprobe (used to obtain audio technical parameters; works fine without it) | ## โœ… Verify File Integrity Each Release includes a `checksums.txt` file for verifying the integrity of downloaded files: ```bash # Download the checksums file wget https://github.com/songloft-org/songloft/releases/latest/download/checksums.txt # Verify the files sha256sum -c checksums.txt ``` ## ๐Ÿ“Œ Version Check ```bash # View version info (including Git Commit / build time / build type) ./songloft -version # View full help ./songloft -help # Check the version via the API curl http://localhost:58091/api/v1/version ``` Example output: ```text Songloft Version: x.y.z Git Commit: abc1234 Build Time: 2026-01-01_00:00:00 Build Type: full ``` ## ๐Ÿ”Œ Plugin System Songloft ships with a built-in JS plugin engine. Plugins run inside a QuickJS sandbox with a permission model, health checks, and hot reload, letting you freely extend audio sources / metadata / device control and more. ### ๐ŸŽฏ Getting Plugins Each plugin is distributed under its own GitHub repository: go to the repository's Releases page to download the latest `.jsplugin.zip`, then upload it on the "Plugin Management" page of the Songloft client to enable it. You can find the current list of available plugins in the [Plugin Collection Issue](https://songloft.hanxi.cc/issues/4). > Want to see more plugins or contribute? Feel free to leave a comment on the [Plugin Collection Issue](https://songloft.hanxi.cc/issues/4). > โš ๏ธ **Copyright notice**: The copyright of any network audio sources, lyrics, covers, or other content accessed by third-party plugins belongs to their respective rights holders. Please use plugins only to access content you personally have the legal right to use, and comply with the laws and regulations of your country or region when downloading / storing / redistributing content. See the [Copyright and Disclaimer](#๏ธ-copyright-and-disclaimer) section above for details. ### ๐Ÿ› ๏ธ Plugin Development To develop custom plugins, refer to the following resources: - **Development toolchain**: [songloft-org/plugin-toolchain](https://github.com/songloft-org/plugin-toolchain) โ€” `@songloft/plugin-sdk` + `@songloft/plugin-builder` + scaffolding - **Quick start**: `pnpm create songloft-plugin ` โ€” see the [JS Plugin Development Guide](./docs/js-plugin-development-guide.md) for details ## ๐Ÿ“– API Documentation The full API documentation (Swagger/OpenAPI format) is available at: - **Swagger API doc**: [swagger.json](https://github.com/songloft-org/songloft/blob/main/docs/swagger.json) - **View Swagger UI online**: [petstore.swagger.io](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/songloft-org/songloft/refs/heads/main/docs/swagger.json) - **View locally**: After starting the service, visit `http://localhost:58091/swagger/index.html` ### Main API Overview | API group | Path | Description | |--------|------|------| | Auth | `/api/v1/auth/*` | Login, refresh token, logout, token management | | Songs | `/api/v1/songs/*` | Song CRUD, covers, playback, lyrics | | Playlists | `/api/v1/playlists/*` | Playlist CRUD, playlist song management, import/export | | JS plugins | `/api/v1/jsplugins/*` | Plugin upload, enable, disable, delete, check for updates | | Scan | `/api/v1/scan/*` | Music library scanning | | Config | `/api/v1/configs/*` | System configuration management (generic KV) | | Settings | `/api/v1/settings/*` | Business feature settings (music directory, HLS proxy, HTTP proxy, auto scan, etc.) | | Cache management | `/api/v1/cache-manage/*` | Cache stats, cleanup, configuration | | Upgrade | `/api/v1/upgrade/*` | Version check, upgrade (Docker only) | | Version | `/api/v1/version` | Version info | | Health | `/api/v1/health` | Service health status | | Proxy | `/api/v1/proxy` | Resource proxy (for CORS issues) | | Logs | `/api/v1/logs/export` | Log export | ## โ“ FAQ Running into problems? See [Frequently Asked Questions and Solutions](https://songloft.hanxi.cc/faq) ๐Ÿ’ฌ ## ๐Ÿ› ๏ธ Support - **GitHub**: [songloft-org/songloft](https://github.com/songloft-org/songloft) - **Issues**: [Issues and feedback](https://github.com/songloft-org/songloft/issues) - ๐Ÿ’ฌ Join the WeChat group: [WeChat group QR code](https://github.com/songloft-org/songloft/issues/2) - ๐Ÿง QQ group: 979995241 (if full, search for a new group) ## ๐Ÿ“ Changelog For detailed release notes, see [CHANGELOG.md](CHANGELOG.md). --- ## ๐Ÿ“„ License This project is open-sourced under the [Apache-2.0 License](LICENSE).