SQL-based paging everywhere, and various other changes

.gitignore

@@ -127,3 +127,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+Jetbrains stuff
+.idea/

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Sacha Bron
+Copyright (c) 2025 Florent Le Moël
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

NOTICE.md

@@ -0,0 +1,29 @@
+# Dependency Licenses
+
+This fork includes code from the parent project. The original license and copyright notices are preserved below.
+
+---
+
+## beetsream
+
+MIT License
+
+Copyright (c) 2020 Sacha Bron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,87 +1,226 @@
-# Beetstream
+<br />
 
-Beetstream is a [Beets.io](https://beets.io) plugin that exposes [SubSonic API endpoints](http://www.subsonic.org/pages/api.jsp), allowing you to stream your music everywhere.
+<div align="center">
 
-## Motivation
+  <a href="https://github.com/FlorentLM/BeetstreamNext">
+    <img src="beetstreamnext.svg" alt="Logo" width="128" height="128">
+  </a>
 
-I personally use Beets to manage my music library on a Raspberry Pi but when I was looking for a way to stream it to my phone I couldn't find any comfortable, suitable and free options.  
-I tried [AirSonic](https://airsonic.github.io) and [SubSonic](http://www.subsonic.org), [Plex](https://www.plex.tv) and some other tools but a lot of these solutions want to manage the library as they need (but I prefer Beets) and AirSonic/SubSonic were quite slow and CPU intensive and seemed to have a lot of overhead just to browse albums and send music files. Thus said, SubSonic APIs are good and implemented by a lot of different [clients](#supported-clients), so I decided to re-implement the server side but based on Beets database (and some piece of code).
+<h3 align="center">BeetstreamNext</h3>
+  <p>
+  A modern, feature-rich OpenSubsonic API server for your Beets.io music library.
+  <br/>
 
-## Install & Run
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)  
 
-Requires Python 3.8 or newer.
+  </p>
+</div>
 
-1) First of all, you need to [install Beets](https://beets.readthedocs.io/en/stable/guides/main.html):
 
-2) Install the dependancies with:
+BeetstreamNext is a fork of Beetstream, a [Beets.io](https://beets.io) plugin that exposes [OpenSubsonic API endpoints](https://opensubsonic.netlify.app/docs/opensubsonic-api/), allowing you to stream your Beets library.
 
-```
-$ pip install beetstream
-```
+I started implementing new features to Beetstream but ended up rewriting a significant part of it, so I figured it'd make more sense to keep it as a distinct project.
+The goal is to cover all of the modern OpenSubsonic API, with some additions. I'm getting there :)
 
-3) Enable the plugin for Beets in your config file `~/.config/beets/config.yaml`:
-```yaml
-plugins: beetstream
-```
+Personally, I use Beets to manage my music library but I don't like to write metadata to the files. So with this, I can have the best of both worlds.
+
+## Key Features
+
+-   **Extensive API coverage**: Implements a wide range of OpenSubsonic endpoints, soon to cover everything.
+-   **On-the-fly transcoding**: As in the original project, this uses **FFmpeg** to transcode audio in real-time to your desired bitrate. Direct streaming is also supported.
+-   **Full cover art support**: Serves artwork from multiple sources:
+    -   Local album art path from your Beets library
+    -   Fallback to the [Cover Art Archive](https://coverartarchive.org/) using MusicBrainz IDs
+    -   Fetches and caches artist images from the [Deezer API](https://developers.deezer.com/api)
+    -   Extracts embedded artwork directly from media files
+-   **Dynamic Playlist management**:
+    -   Reads `.m3u` playlists from specified directories
+    -   Supports creating and deleting playlists directly through the API
+    -   Integrates with Beets' native `playlist` and `smartplaylist` plugins
+-   **Rich metadata integration**: Fetches optional artist info like biographies, top tracks, and similar artists from the [Last.fm API](https://www.last.fm/api)
+
+-   **COMING SOON: Multi-user support**: Dedicated SQLite database to manage users, ratings, bookmarks, and starred content (full multi-user endpoints are in development)
+-   **COMING SOON: Actual authentication**: User credentials, encryption at rest
+
+## Installation
+
+Requires Python 3.9.1 or newer.
+
+> [!NOTE]
+> BeetstreamNext is not yet available on PyPI. Installation currently requires cloning the source code from GitHub.
+
+[//]: # (### For Users)
+
+1.  **Install Beets**: If you haven't already, [install and configure Beets](https://beets.readthedocs.io/en/stable/guides/main.html). You will also need `git` installed on your system.
+
+2.  **Clone the BeetstreamNext Repository**:
+    ```bash
+    git clone https://github.com/FlorentLM/BeetstreamNext.git
+    cd BeetstreamNext
+    ```
+
+3.  **Install the Plugin**:
+    From inside the `BeetstreamNext` directory, run the installation command. You can use `pip` or any modern installer like `uv`.
+    ```bash
+    pip install .
+    ```
+    For transcoding, you will also need to have **FFmpeg** installed and available in your system's PATH.
+
+4.  **Enable the Plugin**: Add `beetstreamnext` to the `plugins` section of your Beets config file (`~/.config/beets/config.yaml`):
+    ```yaml
+    plugins: beetstreamnext
+    ```
+
+5.  **Run the Server**:
+    ```bash
+    beet beetstreamnext
+    ```
+
+[//]: # (### For Developers)
+
+[//]: # ()
+[//]: # (If you want to contribute to BeetstreamNext, the setup process uses [Poetry]&#40;https://python-poetry.org/&#41; for dependency management.)
+
+[//]: # ()
+[//]: # (1.  **Clone the repository**:)
+
+[//]: # (    ```bash)
+
+[//]: # (    git clone https://github.com/FlorentLM/BeetstreamNext.git)
+
+[//]: # (    cd BeetstreamNext)
+
+[//]: # (    ```)
+
+[//]: # ()
+[//]: # (2.  **Install dependencies**:)
+
+[//]: # (    This will create a virtual environment and install all required packages for development and testing.)
+
+[//]: # (    ```bash)
+
+[//]: # (    poetry install)
 
-4) **Optional** You can change the host and port in your config file `~/.config/beets/config.yaml`.  
-You can also chose to never re-encode files even if the clients asks for it with the option `never_transcode: True`. This can be useful if you have a weak CPU or a lot of clients.
+[//]: # (    ```)
+
+[//]: # ()
+[//]: # (3.  **Activate the environment**:)
+
+[//]: # (    ```bash)
+
+[//]: # (    poetry shell)
+
+[//]: # (    ```)
+
+[//]: # ()
+[//]: # (4.  **Run the server**:)
+
+[//]: # (    From inside the activated shell, you can run the plugin directly.)
+
+[//]: # (    ```bash)
+
+[//]: # (    beet beetstreamnext)
+
+[//]: # (    ```)
+
+[//]: # (See the [**CONTRIBUTING.md**]&#40;./CONTRIBUTING.md&#41; file for more details on running tests and submitting changes.)
+
+## Configuration
+
+You can configure BeetstreamNext in your Beets `config.yaml` file. Here are the available options with their default values:
 
-Here are the default values:
 ```yaml
-beetstream:
+beetstreamnext:
   host: 0.0.0.0
   port: 8080
-  never_transcode: False
+  never_transcode: False        # Never re-encode files, even if a client requests it.
+
+  # Artist Image Handling
+  fetch_artists_images: True    # Fetch artist photos from Deezer when a client requests them.
+  save_artists_images: True     # Save fetched artist photos to their respective folders.
+
+  # Playlist Configuration
+  playlist_dirs:                # A list of directories to scan for .m3u playlists.
+    - '/path/to/my/playlists'
+    - '/another/path/for/playlists'
 ```
 
-5) Run with:
-```
-$ beet beetstream
-```
+### Environment Variables
+
+Some features require API keys or secrets, which should be configured as environment variables for security. You can place these in a `.env` file in the directory where you run the `beet` command.
+
+[//]: # (-   **`BEETSTREAMNEXT_KEY` &#40;Required for User features&#41;**: A unique encryption key for storing user data. You can generate one by running this Python command:)
+
+[//]: # (    ```bash)
+
+[//]: # (    python -c "from cryptography.fernet import Fernet; print&#40;Fernet.generate_key&#40;&#41;.decode&#40;&#41;&#41;")
+
+[//]: # (    ```)
+
+-   **`LASTFM_API_KEY` (Optional)**: Your API key from Last.fm to enable fetching artist bios, top tracks, and similar songs.
+    ```
+    LASTFM_API_KEY="your_lastfm_api_key_here"
+    ```
 
-## Clients Configuration
+## Client Configuration
 
 ### Authentication
 
-There is currently no security whatsoever. You can put whatever user and password you want in your favorite app.
+The backend for a full, multi-user authentication system is under active development. For now, **you can use any username and password** in your client to connect to the server. The server will respond as a default "admin" user.
 
 ### Server and Port
 
-Currently runs on port `8080`. i.e: `https://192.168.1.10:8080`. You can configure it in `~/.config/beets/config.yaml`. Defaults are:
-```yaml
-beetstream:
-  host: 0.0.0.0
-  port: 8080
-```
+Connect your client to the server's IP address and the configured port (default is `8080`). For example: `http://192.168.1.10:8080`.
 
 ## Supported Clients
 
-All clients below are working with this server. By "working", it means one can use most of the features, browse library and most importantly play music!
+BeetstreamNext aims for broad compatibility with any Subsonic-compliant player. It has been successfully tested with the following clients:
+
+#### Android
+- [Symfonium](https://symfonium.app/)
+- [Tempo](https://github.com/CappielloAntonio/tempo)
+- [SubTune](https://github.com/TaylorKunZhang/SubTune)
+- [substreamer](https://substreamerapp.com/)
+- [Ultrasonic](https://gitlab.com/ultrasonic/ultrasonic)
+
+#### Desktop
+- [Supersonic](https://github.com/dweymouth/supersonic)
 
-### Android
+## Roadmap
 
-- [Subsonic](https://play.google.com/store/apps/details?id=net.sourceforge.subsonic.androidapp) (official app)
-- [DSub](https://play.google.com/store/apps/details?id=github.daneren2005.dsub)
-- [Audinaut](https://play.google.com/store/apps/details?id=net.nullsum.audinaut)
-- [Ultrasonic](https://play.google.com/store/apps/details?id=org.moire.ultrasonic)
-- [GoSONIC](https://play.google.com/store/apps/details?id=com.readysteadygosoftware.gosonic)
-- [Subtracks](https://play.google.com/store/apps/details?id=com.subtracks)
-- [Music Stash](https://play.google.com/store/apps/details?id=com.ghenry22.mymusicstash)
-- [substreamer](https://play.google.com/store/apps/details?id=com.ghenry22.substream2)
+This project is under active development. Here is a high-level overview of planned features and missing endpoints.
 
-### Desktop
+#### Core Features (In Progress)
+-   [ ] Finalize BeetstreamNext's database storage for multi-user data
+-   [ ] Implement a complete, secure authentication and user management system
+-   [ ] Create a Docker image
 
-- [Clementine](https://www.clementine-player.org)
+#### Missing API Endpoints
+These endpoints require the database and user management systems to be fully operational:
+- `getUsers`, `createUser`, `updateUser`, `deleteUser`
+- `changePassword`
+- `updatePlaylist`
+- `getAvatar`
+- `star`, `unstar`, `setRating`
+- `getBookmarks`, `createBookmark`, `deleteBookmark`
 
-### Web
+#### Future API Endpoints
+- `getLyrics`
+- `getPlayQueue`, `savePlayQueue`
+- `getScanStatus`, `startScan`
 
-- [Jamstash](http://jamstash.com) ([Chrome App](https://chrome.google.com/webstore/detail/jamstash/jccdpflnecheidefpofmlblgebobbloc))
-- [SubFire](http://subfireplayer.net)
+#### Video, Radio & Podcast Endpoints
+These are lower priority but may be considered in the future.
+- `getVideos`, `getVideoInfo`, `hls`, `getCaptions`
+- `getPodcasts`, `getNewestPodcasts`, etc.
+- `getInternetRadioStations` and related endpoints.
 
-_Currently supports a subset of API v1.16.1, avaiable as Json, Jsonp and XML._
+#### Social Endpoints
+- `getNowPlaying`
+- `getShares`, `createShare`, `updateShare`, `deleteShare`
+- `jukeboxControl`
+- `getChatMessages`, `addChatMessage`
 
-## Contributing
+## License
 
-There is still some [missing endpoints](missing-endpoints.md) and `TODO` in the code.
-Feel free to create some PR!
+This project is licensed under the MIT License. See the `LICENSE` file for details.