123a409e14
This commit introduces the README.md file for the SoundSonic project. It provides a comprehensive overview of the project, its features, technologies used, installation instructions, API endpoints, user roles, configuration details, development guidance, supported extensions, license, contributing guidelines, and acknowledgments.
150 lines
3.3 KiB
Markdown
150 lines
3.3 KiB
Markdown
# SoundSonic
|
|
|
|
A Rust-based music streaming server implementing the OpenSubsonic API protocol.
|
|
|
|
## Overview
|
|
|
|
SoundSonic is a lightweight music streaming server built with Rust that implements the [OpenSubsonic](https://opensubsonic.netlify.app/) API specification. It allows you to stream your music collection to any OpenSubsonic-compatible client.
|
|
|
|
## Features
|
|
|
|
- **OpenSubsonic API Support**: Compatible with any client supporting the OpenSubsonic protocol
|
|
- **User Management**: Role-based access control with customizable user permissions
|
|
- **SQLite Database**: Lightweight local storage with Diesel ORM
|
|
- **RESTful API**: Clean, well-structured API endpoints
|
|
- **Async Runtime**: Built on Tokio for high performance
|
|
|
|
## Technologies
|
|
|
|
- **Rust** (Edition 2024)
|
|
- **Axum** - Web framework
|
|
- **Tokio** - Async runtime
|
|
- **Diesel** - ORM with SQLite
|
|
- **Serde** - Serialization/deserialization
|
|
|
|
## Prerequisites
|
|
|
|
- Rust (latest stable version)
|
|
- SQLite
|
|
- Diesel CLI (for database migrations)
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd soundsonic
|
|
```
|
|
|
|
2. Set up the database URL:
|
|
```bash
|
|
export DATABASE_URL=database.db
|
|
```
|
|
|
|
Or create a `.env` file:
|
|
```
|
|
DATABASE_URL=database.db
|
|
```
|
|
|
|
3. Run database migrations:
|
|
```bash
|
|
diesel migration run
|
|
```
|
|
|
|
4. Build and run the server:
|
|
```bash
|
|
cargo run
|
|
```
|
|
|
|
The server will start on `http://0.0.0.0:3311`
|
|
|
|
## API Endpoints
|
|
|
|
### System
|
|
|
|
- `GET/POST /rest/getOpenSubsonicExtensions` - Get supported OpenSubsonic extensions
|
|
|
|
### User Management
|
|
|
|
- `GET/POST /rest/createUser.view` - Create a new user with specified permissions
|
|
|
|
### 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
|
|
|
|
[Your License Here]
|
|
|
|
## 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
|