cae0136aaf
Clarify that the project implements *parts* of the OpenSubsonic API. Add a section detailing the current status and explicitly list implemented features. Update installation steps to include installing the Diesel CLI. Add an example for the `createUser.view` endpoint.
169 lines
3.8 KiB
Markdown
169 lines
3.8 KiB
Markdown
# SoundSonic
|
|
|
|
A Rust-based server implementing parts of the OpenSubsonic API protocol.
|
|
|
|
## Overview
|
|
|
|
SoundSonic is a lightweight server built with Rust that implements the [OpenSubsonic](https://opensubsonic.netlify.app/) API specification. The long-term goal is to support streaming a local music collection to OpenSubsonic-compatible clients.
|
|
|
|
## Status
|
|
|
|
This project is under active development. Only a small subset of the OpenSubsonic API is implemented today (see **API Endpoints**).
|
|
|
|
## Features
|
|
|
|
- **OpenSubsonic Response Envelope**: Consistent `subsonic-response` JSON format
|
|
- **OpenSubsonic Extensions Endpoint**: Exposes supported extensions via `getOpenSubsonicExtensions`
|
|
- **User Creation**: `createUser.view` endpoint with role/permission fields
|
|
- **SQLite + Diesel**: Lightweight local storage
|
|
- **Axum + Tokio**: Async HTTP server runtime
|
|
|
|
## Technologies
|
|
|
|
- **Rust** (Edition 2024)
|
|
- **Axum** - Web framework
|
|
- **Tokio** - Async runtime
|
|
- **Diesel** - ORM with SQLite
|
|
- **Serde** - Serialization/deserialization
|
|
|
|
## Prerequisites
|
|
|
|
- Rust (latest stable version)
|
|
- SQLite (system library)
|
|
- Diesel CLI (for database migrations)
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <your-repository-url>
|
|
cd soundsonic
|
|
```
|
|
|
|
2. Install Diesel CLI (SQLite):
|
|
```bash
|
|
cargo install diesel_cli --no-default-features --features sqlite
|
|
```
|
|
|
|
3. Set up the database URL:
|
|
```bash
|
|
export DATABASE_URL=database.db
|
|
```
|
|
|
|
Or create a `.env` file:
|
|
```
|
|
DATABASE_URL=database.db
|
|
```
|
|
|
|
4. Run database migrations:
|
|
```bash
|
|
diesel migration run
|
|
```
|
|
|
|
5. Build and run the server:
|
|
```bash
|
|
cargo run
|
|
```
|
|
|
|
The server will start on `http://0.0.0.0:3311`.
|
|
|
|
## API Endpoints
|
|
|
|
All endpoints are nested under the `/rest` prefix.
|
|
|
|
### System
|
|
|
|
- `GET /rest/getOpenSubsonicExtensions`
|
|
- `POST /rest/getOpenSubsonicExtensions`
|
|
|
|
### User Management
|
|
|
|
- `GET /rest/createUser.view`
|
|
- `POST /rest/createUser.view` (accepts `application/x-www-form-urlencoded`)
|
|
|
|
Example:
|
|
```bash
|
|
curl -X POST 'http://localhost:3311/rest/createUser.view' \
|
|
-d 'username=alice&password=secret&email=alice@example.com&adminRole=true&streamRole=true'
|
|
```
|
|
|
|
### Request/Response Format
|
|
|
|
All API responses follow the OpenSubsonic response format:
|
|
|
|
```json
|
|
{
|
|
"subsonic-response": {
|
|
"status": "ok",
|
|
"version": "1.16.1",
|
|
"type": "SoundSonic",
|
|
"serverVersion": "1.16.1",
|
|
"openSubsonic": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## User Roles
|
|
|
|
Users can have the following permissions:
|
|
|
|
- `adminRole` - Administrative privileges
|
|
- `streamRole` - Stream music
|
|
- `downloadRole` - Download music
|
|
- `uploadRole` - Upload music
|
|
- `playlistRole` - Manage playlists
|
|
- `coverArtRole` - Manage cover art
|
|
- `commentRole` - Add comments
|
|
- `podcastRole` - Access podcasts
|
|
- `shareRole` - Share content
|
|
- `jukeboxRole` - Jukebox control
|
|
- `videoConversionRole` - Video conversion
|
|
- `settingsRole` - Change settings
|
|
- `ldapAuthenticated` - LDAP authentication
|
|
|
|
## Configuration
|
|
|
|
The server can be configured via environment variables:
|
|
|
|
- `DATABASE_URL` - Path to the SQLite database file (required)
|
|
|
|
## Development
|
|
|
|
### Running in development mode:
|
|
```bash
|
|
cargo run
|
|
```
|
|
|
|
### Building for production:
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
### Database schema changes:
|
|
```bash
|
|
diesel migration generate <migration_name>
|
|
diesel migration run
|
|
```
|
|
|
|
## Supported OpenSubsonic Extensions
|
|
|
|
- `apiKeyAuthentication` - API key-based authentication
|
|
- `formPost` - Form-based POST requests
|
|
- `indexBasedQueue` - Index-based queue management
|
|
- `songLyrics` - Song lyrics support
|
|
- `transcodeOffset` - Transcoding offset support
|
|
- `transcoding` - Audio transcoding capabilities
|
|
|
|
## License
|
|
|
|
MIT (see `LICENSE`).
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
|
|
## Acknowledgments
|
|
|
|
- [OpenSubsonic](https://opensubsonic.netlify.app/) - The API specification this server implements
|
|
- [Subsonic](http://www.subsonic.org/) - The original music streaming server
|