Batyka/soundcloak
1
0
Fork 0
mirror of https://git.maid.zone/stuff/soundcloak.git synced 2025-12-10 05:39:38 +05:00
Code Issues Packages Projects Releases Wiki Activity

big documentation changes

Browse Source
This commit is contained in:
Laptop
2024-12-23 12:05:05 +02:00
parent 912670541a
commit 4f81686ff0
11 changed files with 705 additions and 335 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/AUDIO_PRESETS.md Normal file
View File

@@ -0,0 +1,6 @@
| Name | Container | Codec | Observed bitrate | Note |
| ------ | ------------ | ------- | ------------------ | ---------------------------------------------------------------------------------------- |
| Best | | | | Prefer AAC over Opus over MPEG. Not supported for HLS player (use AAC for same effect) |
| AAC | mp4 (m4a) | AAC | 160kbps | Rarely available. Falls back to MPEG if unavailable |
| Opus | ogg | Opus | 72kbps | Usually available. Falls back to MPEG if unavailable. Not supported for HLS player |
| MP3 | mpeg (mp3) | MP3 | 128kbps | Always available. Good for compatibility |

93
docs/DEV_GUIDE.md Normal file
View File

@@ -0,0 +1,93 @@
# Setup
## Prerequisites
1. [node.js + npm](https://nodejs.org) (any recent enough version should do, it's just used for getting hls.js builds)
2. [golang](https://go.dev) (I recommend version 1.22.10. Technically, you need 1.21.4 or higher)
3. [git](https://git-scm.com)
## The setup
1. Clone this repository:
```sh
git clone https://github.com/maid-zone/soundcloak
```
2. Go into the cloned repository:
```sh
cd soundcloak
```
3. Download hls.js:
```sh
npm i
```
4. Download templ:
```sh
go install github.com/a-h/templ/cmd/templ@latest
```
5. Download regexp2cg:
Not really required, but helps speed up some parts of the code that use regular expressions by generating code for them instead of compiling in runtime.
```sh
go install github.com/dlclark/regexp2cg@main
```
*You might need to add go binaries to your PATH (add this line to your .bashrc / .zshrc / whatever)*
```sh
export PATH=${PATH}:`go env GOPATH`/bin
```
6. Build binary:
This uses the `build` script, which generates code from templates, generates code for regular expiressions, and then builds the binary.
```sh
./build
```
Now, you can run soundcloak with the `./main` binary. By default, it is listening on `127.0.0.1:4664`. For a configuration guide, [refer to here](INSTANCE_GUIDE.md#configuration-guide)
# Updating your local setup
1. Retrieve the latest code:
```sh
git fetch origin
git pull
```
2. Update dependencies/tools:
```sh
npm i # for hls.js
go get # for other go packages
go install github.com/a-h/templ/cmd/templ@latest # templ cli
go install github.com/dlclark/regexp2cg@main # regexp2 codegen cli. not required unless you've installed it
```
3. Clean precompressed static files
Those are created by the webserver in order to more efficiently serve static files. They have the `.fiber.gz` extension. You can easily remove them from all directories like this:
```sh
find . -name \*.fiber.gz -type f -delete
```
4. Run codegen and build the binary:
```sh
./build
```
Now, you can run soundcloak with the `./main` binary.
# Contributing
Contributions are appreciated!
If you want to add a new feature that's not in [the todo list](https://github.com/maid-zone/soundcloak/discussions/6), please create an issue or discussion first.
If you have updated go dependencies or added new ones, please run `go mod tidy` before commiting.
Any security vulnerabilities should first be disclosed privately to the maintainer ([different ways to contact me are listed here](https://laptopc.at))

156
docs/INSTANCE_GUIDE.md Normal file
View File

@@ -0,0 +1,156 @@
# Setup
## Docker
You need to have [Docker](https://docker.com) and [Git](https://git-scm.com) installed.
1. Clone this repository:
```sh
git clone https://github.com/maid-zone/soundcloak
```
2. Go into the cloned repository:
```sh
cd soundcloak
```
3. Make a copy of the example compose.yaml file:
```sh
cp compose.example.yaml compose.yaml
```
Make adjustments as needed.
4. *Optional.* Edit config:
Refer to [Configuration guide](#configuration-guide) for configuration information. Can be configured from environment variables or JSON file.
5. Run the container:
```sh
docker compose up -d
```
You might need to use `sudo` if you aren't running as root.
Use `docker-compose` instead of `docker compose` if that fails.
Soundcloak will now be up at `127.0.0.1:4664` (or the address you specified in your config). I recommend you run it through a reverse proxy (caddy, nginx, etc.)
## Regular method
Refer to the [developer guide](DEV_GUIDE.md#setup)
# Updating your instance
## Docker
1. Retrieve the latest code:
```sh
git fetch origin
git pull
```
2. Stop the container:
```sh
docker container stop soundcloak
```
3. Build the container with updated source code:
```sh
docker compose build
```
4. Start the container:
```sh
docker compose up -d
```
Use `docker-compose` instead of `docker compose` if that fails.
## Regular method
Refer to the [developer guide](DEV_GUIDE.md#updating-your-local-setup)
# Configuration/customization
## Configuration guide
<details>
<summary>Click to view</summary>
You can only configure in one of the two ways:
- Using config file (`soundcloak.json` in current directory // your own path and filename)
- Using environment variables (`SOUNDCLOAK_CONFIG` must be set to `FROM_ENV`!)
Some notes:
- When specifying time, specify it in seconds.
| JSON key | Environment variable | Default value | Description |
| ----------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| None | SOUNDCLOAK_CONFIG | soundcloak.json | File to load soundcloak config from. If set to `FROM_ENV`, soundcloak loads the config from environment variables. |
| GetWebProfiles | GET_WEB_PROFILES | true | Retrieve links users set in their profile (social media, website, etc) |
| DefaultPreferences | DEFAULT_PREFERENCES | {"Player": "hls", "ProxyStreams": false, "FullyPreloadTrack": false, "ProxyImages": false, "ParseDescriptions": true, "AutoplayNextTrack": false, "DefaultAutoplayMode": "normal", "HLSAudio": "mpeg", "RestreamAudio": "mpeg", "DownloadAudio": "mpeg"} | see /_/preferences page. [Read more](PREFERENCES.md) |
| ProxyImages | PROXY_IMAGES | false | Enables proxying of images (user avatars, track covers etc) |
| ImageCacheControl | IMAGE_CACHE_CONTROL | max-age=600, public, immutable | [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header value for proxied images. Cached for 10 minutes by default. |
| ProxyStreams | PROXY_STREAMS | false | Enables proxying of song parts and hls playlist files |
| Restream | RESTREAM | false | Enables Restream Player in settings and the /_/restream/:author/:track endpoint. This player can be used without JavaScript. Restream also enables the button for downloading songs. |
| RestreamCacheControl | RESTREAM_CACHE_CONTROL | max-age=3600, public, immutable | [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header value for restreamed songs. Cached for 1 hour by default. |
| ClientIDTTL | CLIENT_ID_TTL | 4 hours | Time until ClientID cache expires. ClientID is used for authenticating with SoundCloud API |
| UserTTL | USER_TTL | 20 minutes | Time until User profile cache expires |
| UserCacheCleanDelay | USER_CACHE_CLEAN_DELAY | 5 minutes | Time between each cleanup of the cache (to remove expired users) |
| TrackTTL | TRACK_TTL | 20 minutes | Time until Track data cache expires |
| TrackCacheCleanDelay | TRACK_CACHE_CLEAN_DELAY | 5 minutes | Time between each cleanup of the cache (to remove expired tracks) |
| PlaylistTTL | PLAYLIST_TTL | 20 minutes | Time until Playlist data cache expires |
| PlaylistCacheCleanDelay | PLAYLIST_CACHE_CLEAN_DELAY | 5 minutes | Time between each cleanup of the cache (to remove expired playlists) |
| UserAgent | USER_AGENT | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.3 | User-Agent header used for requests to SoundCloud |
| DNSCacheTTL | DNS_CACHE_TTL | 60 minutes | Time until DNS cache expires |
| Addr | ADDR | :4664 | Address and port for soundcloak to listen on |
| Prefork | PREFORK | false | Run multiple instances of soundcloak locally to be able to handle more requests. Each one will be a separate process, so they will have separate cache. |
| TrustedProxyCheck | TRUSTED_PROXY_CHECK | true | Use X-Forwarded-* headers if IP is in TrustedProxies list. When disabled, those headers will blindly be used. |
| TrustedProxies | TRUSTED_PROXIES | [] | List of IPs or IP ranges of trusted proxies |
</details>
## Tinkering with the frontend
<details>
<summary>Click to view</summary>
I will mainly talk about the static files here. Maybe about the templates too in the future
The static files are stored in `assets` folder
### Overriding files
1. Create a folder named `instance`
2. Create a file with the same name as the one you want to override
3. Put whatever you want there
### Basic theming
1. Create `instance.css` file in the `instance` folder
2. Put your CSS rules there:
```css
/* Some basic CSS to change colors of the frontend. Put your own colors here as this one probably looks horrible (I did not test it) */
:root {
--accent: #ffffff;
--primary: #000000;
--secondary: #00010a;
--0: #fafafa; /* Used for things, such as border color for buttons, etc */
--text: green;
}
```
Refer to `assets/global.css` file for existing rules.
</details>
# Instance list
To get listed on [the instance list](https://maid.zone/soundcloak/instances.html), create a discussion with some information about your instance, or [reach out privately](https://laptopc.at)
Basic rules:
1. Do not collect user information (either yourself, or by including 3rd party tooling which does that)
2. If you are modifying the source code, publish those changes somewhere. Even if it's just static files, it would be best to publish those changes somewhere.
Also, keep in mind that the instance list will periodically hit the `/_/info` endpoint on your instance (usually each 10 minutes) in order to display the instance settings. If you do not want this to happen, state it in your discussion/message, and I will exclude your instance from this checking.
The source code powering the instance list can be found [here](https://github.com/maid-zone/soundcloak-instances)

343
docs/OLD_README.md Normal file
View File

@@ -0,0 +1,343 @@
# soundcloak
wip alternative frontend for soundcloud
# [Instance list](https://maid.zone/soundcloak/instances.html)
# Already implemented
- Searching for songs, users, playlists
- Basic user overview (songs, playlists, albums, reposts, metadata)
- Basic song overview (author, metadata) & streaming (requires some JS if instance has `Restream` disabled)
- Basic playlist/set/album overview (songs list, author, metadata)
- Resolving shortened links (`https://on.soundcloud.com/boiKDP46fayYDoVK9` -> `https://sc.maid.zone/on/boiKDP46fayYDoVK9`)
- Content proxying (images, audio)
- View featured tracks, playlists
- Users can change their preferences (should proxying be enabled, what method of playing the song should be used etc)
- Viewing popular/recent tracks/playlists with a certain tag/genre (actually working for playlists, unlike soundcloud itself!)
## In the works
- Track player embeds (`https://w.soundcloud.com/player/` -> `https://sc.maid.zone/w/player/`)
The UI isn't really done yet. All parameters other than url are unsupported. You can also specify track without the `soundcloud.com` part: `https://sc.maid.zone/w/player/?url=<id>` or `https://sc.maid.zone/w/player/?url=<user>/<track>`
# Settings
## Viewing instance config
If the instance isn't outdated and has `InstanceInfo` setting enabled, you can navigate to `<instance>/_/info` to view useful instance settings. ([sc.maid.zone/_/info](https://sc.maid.zone/_/info) for example)
## Preferences
You can go to `/_/preferences` page to configure them. You can view default preferences using the method described above or by resetting your preferences.
You can also Export/Import your preferences, for backup purposes or for easily transfering them between instances.
- Parse descriptions: Highlight `@username`, `https://example.com` and `email@example.com` in text as clickable links
- Show current audio: shows what [preset](#audio-presets) is currently playing (mpeg, opus or aac)
- Proxy images: Retrieve images through the instance, instead of going to soundcloud's servers for them
- Player: In what way should the track be streamed. Can be Restream (does not require JS, better compatibility, can be a bit buggy client-side) or HLS (requires JS, more stable, less good compatibility (you'll be ok unless you are using a very outdated browser))
- Autoplay next track in playlists: self-explanatory
- Default autoplay mode: Default mode for autoplaying. Can be normal (play songs in order) or random (play random song)
- Player-specific settings:
- - HLS Player:
- - - Proxy streams: Retrieve song pieces through the instance, instead of going to soundcloud's servers for them
- - - Fully preload track: Fully loads the track when you load the page instead of buffering a small part of it
- - - Streaming audio: What [preset](#audio-presets) of audio should be streamed (Opus is not supported here)
- - Restream Player:
- - - Streaming audio: What [preset](#audio-presets) of audio should be streamed
# Contributing
Contributions are appreciated! This includes feedback, feature requests, issues, pull requests and etc.
Feedback and feature requests are especially needed, since I (laptopcat) don't really know what to prioritize
You can contribute on:
- [GitHub](https://github.com/maid-zone/soundcloak)
- [Codeberg (mirror)](https://codeberg.org/maid-zone/soundcloak)
You can also [reach out to me privately](https://laptopc.at)
# Setting it up
<details>
<summary>1. Regular method</summary>
## Prerequisites:
1. [node.js + npm](https://nodejs.org) (any recent enough version should do, it's just used for getting hls.js builds)
2. [golang](https://go.dev) (I recommend version 1.22.10. Technically, you need 1.21.4 or higher)
3. [git](https://git-scm.com)
## Setup:
1. Clone this repository:
```sh
git clone https://github.com/maid-zone/soundcloak
```
2. Go into the cloned repository:
```sh
cd soundcloak
```
3. Download hls.js:
```sh
npm i
```
4. Download templ:
```sh
go install github.com/a-h/templ/cmd/templ@latest
```
5. Download regexp2cg:
Not really required, but helps speed up some parts of the code that use regular expressions. Keep in mind that the `build` script expects this to be installed.
```sh
go install github.com/dlclark/regexp2cg@main
```
*You might need to add go binaries to your PATH (add this line to your .bashrc / .zshrc / whatever)*
```sh
export PATH=${PATH}:`go env GOPATH`/bin
```
6. *Optional.* Edit config:
Refer to [Configuration guide](#configuration-guide) for configuration information. Can be configured from environment variables or JSON file.
7. Build binary:
This uses the `build` script, which generates code from templates, generates code for regular expiressions, and then builds the binary.
```sh
./build
```
8. Run the binary:
```sh
./main
```
This will run soundcloak on localhost, port 4664. (by default)
</details>
<details>
<summary>2. Docker image</summary>
The docker image was made by [vlnst](https://github.com/vlnst)
## Prerequisites:
1. [Docker](https://www.docker.com/)
2. [Git](https://git-scm.com)
## Setup:
1. Clone this repository:
```sh
git clone https://github.com/maid-zone/soundcloak
```
2. Go into the cloned repository:
```sh
cd soundcloak
```
3. Make a copy of the example `compose.yaml` file:
```sh
cp compose.example.yaml compose.yaml
```
Make adjustments as needed.
4. *Optional.* Edit config:
Refer to [Configuration guide](#configuration-guide) for configuration information. Can be configured from environment variables or JSON file.
5. Run the container
```sh
docker compose up -d
```
(if you get `docker: 'compose' is not a docker command.`, use `docker-compose up -d`)
This will run soundcloak as a daemon (remove the -d part of the command to just run it) on localhost, port 4664. (by default)
</details>
# Configuration guide
<details>
<summary>Click to view</summary>
You can only configure in one of the two ways:
- Using config file (`soundcloak.json` in current directory // your own path and filename)
- Using environment variables (`SOUNDCLOAK_CONFIG` must be set to `FROM_ENV`!)
Some notes:
- When specifying time, specify it in seconds.
| JSON key | Environment variable | Default value | Description |
| :------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| None | SOUNDCLOAK_CONFIG | soundcloak.json | File to load soundcloak config from. If set to `FROM_ENV`, soundcloak loads the config from environment variables. |
| GetWebProfiles | GET_WEB_PROFILES | true | Retrieve links users set in their profile (social media, website, etc) |
| DefaultPreferences | DEFAULT_PREFERENCES | {"Player": "hls", "ProxyStreams": false, "FullyPreloadTrack": false, "ProxyImages": false, "ParseDescriptions": true, "AutoplayNextTrack": false, "DefaultAutoplayMode": "normal", "HLSAudio": "mpeg", "RestreamAudio": "mpeg", "DownloadAudio": "mpeg"} | see /_/preferences page. [Read more](#preferences-1) |
| ProxyImages | PROXY_IMAGES | false | Enables proxying of images (user avatars, track covers etc) |
| ImageCacheControl | IMAGE_CACHE_CONTROL | max-age=600, public, immutable | [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header value for proxied images. Cached for 10 minutes by default. |
| ProxyStreams | PROXY_STREAMS | false | Enables proxying of song parts and hls playlist files |
| Restream | RESTREAM | false | Enables Restream Player in settings and the /_/restream/:author/:track endpoint. This player can be used without JavaScript. Restream also enables the button for downloading songs. |
| RestreamCacheControl | RESTREAM_CACHE_CONTROL | max-age=3600, public, immutable | [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header value for restreamed songs. Cached for 1 hour by default. |
| ClientIDTTL | CLIENT_ID_TTL | 4 hours | Time until ClientID cache expires. ClientID is used for authenticating with SoundCloud API |
| UserTTL | USER_TTL | 20 minutes | Time until User profile cache expires |
| UserCacheCleanDelay | USER_CACHE_CLEAN_DELAY | 5 minutes | Time between each cleanup of the cache (to remove expired users) |
| TrackTTL | TRACK_TTL | 20 minutes | Time until Track data cache expires |
| TrackCacheCleanDelay | TRACK_CACHE_CLEAN_DELAY | 5 minutes | Time between each cleanup of the cache (to remove expired tracks) |
| PlaylistTTL | PLAYLIST_TTL | 20 minutes | Time until Playlist data cache expires |
| PlaylistCacheCleanDelay | PLAYLIST_CACHE_CLEAN_DELAY | 5 minutes | Time between each cleanup of the cache (to remove expired playlists) |
| UserAgent | USER_AGENT | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.3 | User-Agent header used for requests to SoundCloud |
| DNSCacheTTL | DNS_CACHE_TTL | 60 minutes | Time until DNS cache expires |
| Addr | ADDR | :4664 | Address and port for soundcloak to listen on |
| Prefork | PREFORK | false | Run multiple instances of soundcloak locally to be able to handle more requests. Each one will be a separate process, so they will have separate cache. |
| TrustedProxyCheck | TRUSTED_PROXY_CHECK | true | Use X-Forwarded-* headers if IP is in TrustedProxies list. When disabled, those headers will blindly be used. |
| TrustedProxies | TRUSTED_PROXIES | [] | List of IPs or IP ranges of trusted proxies |
</details>
## Preferences
<details>
<summary>Click to view</summary>
| Name | Default | Description | Possible values |
| --------------------- | --------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ |
| Player | "restream" if Restream is enabled in config, otherwise - "hls" | Method used to play the track in the frontend. HLS - requires JavaScript, loads the track in pieces. Restream - works without JavaScript, loads entire track right away. None - don't play the track | "hls", "restream", "none" |
| ProxyStreams | same as your config | Proxy track streams. Refer to configuration guide for more info. Not effective unless ProxyStreams is enabled in your config and you are using HLS player (Restream proxies songs by default) | true, false |
| FullyPreloadTrack | false | Fully load track when the page is loaded. Only effective if you are using HLS player | true, false |
| ParseDescriptions | true | Highlight links, usernames and emails in track/user/playlist descriptions | true, false |
| AutoplayNextTrack | false | Automatically start playlist playback when you open a track from it | true, false |
| DefaultAutoplayMode | "normal" | Default mode for autoplay. Normal - play songs in order. Random - play random song next | "normal", "random" |
| HLSAudio | "mpeg" | What audio preset should be loaded when using HLS player. Note that "opus" is not supported here. [Read more](#audio-presets) | "aac", "mpeg" |
| RestreamAudio | "mpeg" | What audio preset should be loaded when using Restream player. [Read more](#audio-presets) | "best", "aac", "opus", "mpeg" |
| DownloadAudio | "mpeg" | What audio preset should be loaded when downloading audio with metadata. [Read more](#audio-presets) | "best", "aac", "opus", "mpeg" |
| ShowAudio | false | Show what audio preset was loaded on the track page | true, false |
</details>
## Audio presets
<details>
<summary>Click to view</summary>
| Name | Container | Codec | Bitrate | Note |
| ---- | ---------- | ----- | ------- | -------------------------------------------------------------------------------------- |
| Best | | | | Prefer AAC over Opus over MPEG. Not supported for HLS player (use AAC for same effect) |
| AAC | mp4 (m4a) | AAC | 160kbps | Rarely available. Falls back to MPEG if unavailable |
| Opus | ogg | Opus | 72kbps | Usually available. Falls back to MPEG if unavailable. Not supported for HLS player |
| MP3 | mpeg (mp3) | MP3 | 128kbps | Always available. Good for compatibility |
</details>
## Tinkering with the frontend
<details>
<summary>Click to view</summary>
I will mainly talk about the static files here. Maybe about the templates too in the future
The static files are stored in `assets` folder
### Overriding files
You can override files by putting identically named files in the `instance` folder.
### Basic theming
1. Create `instance.css` file in `instance` folder
2. Put your CSS rules there:
```css
/* Some basic CSS to change colors of the frontend. Put your own colors here as this one probably looks horrible (I did not test it) */
:root {
--accent: #ffffff;
--primary: #000000;
--secondary: #00010a;
--0: #fafafa; /* Used for things, such as border color for buttons, etc */
--text: green;
}
```
Refer to `assets/global.css` file for existing rules.
</details>
# Maintenance-related stuffs
## Updating
Note: this guide works only if you install from source. If you used docker, you could probably do the 1st step (pulling the code), stop the container (`docker container stop soundcloak`), build it (`docker compose build`) and start it again. (`docker compose up -d`)
<details>
<summary>Click to view</summary>
1. Retrieve the latest code:
```sh
git fetch origin
git pull
```
2. Remove compressed versions of files:
The webserver is configured to locally cache compressed versions of files. They have `.fiber.gz` extension and can be found in `assets` folder and `node_modules/hls.js/dist`. If any static files have been changed, you should purge these compressed files so the new versions can be served. Static files are also cached in user's browser, so you will need to clean your cache to get the new files (Ctrl + F5)
For example, you can clean these files from `assets` folder like so:
```sh
cd assets
rm *.fiber.gz
```
3. *Optional.* Edit config:
Sometimes, new updates add new config values or change default ones. Refer to [Configuration guide](#configuration-guide) for configuration information. Can be configured from environment variables or JSON file.
5. Update hls.js:
```sh
npm i
```
6. Build binary:
```sh
./build
```
7. Run it:
```sh
./main
```
Congratulations! You have succesfully updated your soundcloak.
</details>

37
docs/PREFERENCES.md Normal file
View File

@@ -0,0 +1,37 @@
# Preferences
| Name | Key | Default | Possible values | Description |
| :--------------------------------- | --------------------- | ------------------------------------------------------------------------ | ------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Parse descriptions | ParseDescriptions | true | true, false | Turn @mentions, external links (https://example.org) and emails (hello@example.org) inside descriptions into clickable links |
| Show current audio | ShowAudio | false | true, false | Show what [audio preset](AUDIO_PRESETS.md) is being streamed below the audio player |
| Proxy images | ProxyImages | same as ProxyImages in backend config | true, false | Proxy images through the backend. ProxyImages must be enabled on the backend |
| Download audio | DownloadAudio | "mpeg" | "mpeg", "opus", "aac", "best" | What [audio preset](AUDIO_PRESETS.md) should be loaded when downloading audio with metadata. Restream must be enabled on the backend |
| Autoplay next track in playlists | AutoplayNextTrack | false | true, false | Automatically start playlist playback when you open a track from the playlist. Requires JS |
| Default autoplay mode | DefaultAutoplayMode | "normal" | "normal", "random" | Default mode for autoplay. Normal - play songs in order. Random - play random song next |
| Player | Player | "restream" if Restream is enabled in backend config, otherwise - "hls" | "restream", "hls", "none" | Method used to play the track in the frontend. HLS - requires JavaScript, loads the track in pieces. Restream - works without JavaScript, loads entire track through the backend right away. None - don't play the track |
## Player-specific preferences
### HLS Player
| Name | Key | Default | Possible values | Description |
| :-------------------- | ------------------- | ---------------------------------------- | ----------------- | :------------------------------------------------------------------------------------ |
| Proxy song streams | ProxyStreams | same as ProxyStreams in backend config | true, false | Proxy song streams through the backend. ProxyStreams must be enabled on the backend |
| Fully preload track | FullyPreloadTrack | false | true, false | Fully load track when the page is loaded (track stream expires in ~5 minutes) |
| Streaming audio | HLSAudio | "mpeg" | "mpeg", "aac" | What [audio preset](AUDIO_PRESETS.md) should be loaded when streaming audio |
### HLS Player
| Name | Key | Default | Possible values | Description |
| :-------------------- | ------------------- | ---------------------------------------- | ----------------- | :------------------------------------------------------------------------------------ |
| Proxy song streams | ProxyStreams | same as ProxyStreams in backend config | true, false | Proxy song streams through the backend. ProxyStreams must be enabled on the backend |
| Fully preload track | FullyPreloadTrack | false | true, false | Fully load track when the page is loaded (track stream expires in ~5 minutes) |
| Streaming audio | HLSAudio | "mpeg" | "mpeg", "aac" | What [audio preset](AUDIO_PRESETS.md) should be loaded when streaming audio |
### Restream Player
| Name | Key | Default | Possible values | Description |
| :-------------------- | ------------------- | ---------------------------------------- | ----------------- | :------------------------------------------------------------------------------------ |
| Streaming audio | RestreamAudio | "mpeg" | "mpeg", "opus", "aac", "best" | What [audio preset](AUDIO_PRESETS.md) should be loaded when streaming audio |

51
docs/USER_GUIDE.md Normal file
View File

@@ -0,0 +1,51 @@
# [Instances List](https://maid.zone/soundcloak/instances.html)
# Viewing instance settings
If the instance is in the [instances list](https://maid.zone/soundcloak/instances.html), then you can view a few of the settings there (ProxyStreams, ProxyImages, Restream)
You can also visit `<instance>/_/info` to view some of the settings. This endpoint is only available if `InstanceInfo` is enabled by the maintainer.
Example output: (from [soundcloak.fly.dev/_/info](https://soundcloak.fly.dev/_/info))
```json
{
"Commit": "9126705",
"Repo": "https://github.com/maid-zone/soundcloak",
"ProxyImages": true,
"ProxyStreams": true,
"Restream": true,
"GetWebProfiles": true,
"DefaultPreferences": {
"Player": "restream",
"ProxyStreams": true,
"FullyPreloadTrack": false,
"ProxyImages": true,
"ParseDescriptions": true,
"AutoplayNextTrack": false,
"DefaultAutoplayMode": "normal",
"HLSAudio": "mpeg",
"RestreamAudio": "mpeg",
"DownloadAudio": "mpeg",
"ShowAudio": true
}
}
```
# Preferences
Click the "Preferences" button on the main page, or navigate to `<instance>/_/preferences` to get started.
Instance maintainers can set their own default preferences.
[Refer to here](PREFERENCES.md) for a full list of preferences. If you don't see certain preferences on the page, it means that you have to enable a different preference to configure this one, or this feature has been disabled on the backend.
Those preferences are saved in a cookie.
## Management
Scroll down to the end of the preferences page. There you can see a management tab for preferences. You can export your preferences as a JSON file, import the preferences, or reset them.
# Redirecting from SoundCloud to soundcloak
soundcloak tries to keep the URL schemes same to SoundCloud's, so you can just replace `soundcloud.com` with your instance URL. For short links: `https://on.soundcloud.com/boiKDP46fayYDoVK9` -> `<instance>/on/boiKDP46fayYDoVK9`

BIN
docs/screenshots/1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

BIN
docs/screenshots/2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 123 KiB

BIN
docs/screenshots/3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 174 KiB