marc/scotty
1
0
Fork 0
mirror of https://git.sr.ht/~phw/scotty synced 2025-04-10 23:49:28 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Documented general configuration and usage

Browse source
This commit is contained in:
Philipp Wolfer 2023-12-09 17:41:38 +01:00
parent d6ca8d33f7
commit 0b1806367f
No known key found for this signature in database
GPG key ID: 8FDF744D4919943B
3 changed files with 87 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

87
README.md
View file

@ -28,22 +28,97 @@ This requires `go` to be installed on your system. You can get it from https://g
## Configuration
Scotty requires the configuration of the services in a configuration file in TOML format. See [config.example.toml](./config.example.toml) for details.
To use Scotty you need to configure at least two services (e.g. ListenBrainz, Last.fm, Funkwhale or Spotify).
By default Scotty stores the configuration in a platform dependent configuration directory (e.g. on Unix like system this is `$HOME/.config/scotty/scotty.toml`), but you can also run it with a different configuration file using the `--config` command line parameter.
New services can be configured interactively using the `service add`, `service edit` and `service delete` commands. Run `scotty service --help` for tails.
The configuration file in TOML format can also be edited manually. For a full example see [config.example.toml](./config.example.toml).
## Usage
Run `scotty --help` for command line help.
Run `scotty --help` for general command line help.
### Tutorial
As a full example consider that you want to transfer your listen history and loved tracks from Deezer to ListenBrainz. You first need to configure these services. Let's start with adding ListenBrainz. Run `scotty service add`. Scotty will allow you to interactively configure the service. First you need to select "listenbrainz" as the backend:
```
$ scotty service add
Use the arrow keys to navigate: ↓ ↑ → ←
? Backend:
deezer
dump
funkwhale
jspf
lastfm
▸ listenbrainz
maloja
scrobbler-log
spotify
subsonic
```
Next Scotty will ask how to name this service. You can accept the suggested name "listenbrainz". Naming services differently can be useful when you configure multiple services with the same backend (e.g. multiple separate accounts).
```
✔ listenbrainz
✔ Service name: listenbrainz█
```
Next you need to provide your ListenBrainz user name and [user token](https://listenbrainz.org/profile/):
```
✔ listenbrainz
✔ Service name: listenbrainz
✔ User name: outsidecontext
✔ Access token: *************************************
Saved service listenbrainz using backend listenbrainz
```
*Hint: If you made a mistake and want to change a value, run `scotty service edit` to change the configuration of existing services.*
For Deezer we need access to the Deezer API. You need a Deezer account for which you have to [register an application](https://developers.deezer.com/myapps) in the Deezer developer portal. Give this application any name (e.g. Scotty) and use `http://127.0.0.1:2369/callback/deezer` as the "Redirect URL after authentication". After creating the application note the "Application ID" and "Secret Key".
Now you can add a new service by running `scotty service add` again. Choose the "deezer" backend and set a name (let's use the default "deezer") as well as the Application ID and Secret Key you obtained before.
Before you can use Deezer you need to authorize Scotty to access your account. For this run `scotty service auth --service deezer`. If your Application ID and Secret Key were correct your browser should open with Deezer's login and authorization page. Confirm the access. On success the browser will show "Token received, you can close this window now.". Close the browser window and return to your terminal.
Running `scotty service list` should now show the two services "deezer" and "listenbrainz".
Now you can use these services to transfer data between them. To transfer the loved tracks from Deezer to ListenBrainz run:
```
scotty beam loves deezer listenbrainz
```
The output will look something like this:
```
Transferring loves from deezer to listenbrainz...
From timestamp: 1970-01-01 01:00:01 +0100 CET (1)
✓ exporting [=======================================================] done
✓ importing [=======================================================] done
Imported 4 of 4 loves into listenbrainz.
Latest timestamp: 2023-11-23 14:44:46 +0100 CET (1700747086)
```
Scotty will remember the latest timestamp for which it transferred data between the two services. The next time you run `scotty beam loves deezer listenbrainz` it will only consider tracks loved after the previous import. If you for some reason want to override this and start importing at an earlier time again, you can specify an earlier start time with the `--timestamp` parameter, which expects a Unix timestamp.
For example to import listens starting at a specific timestamp use:
```
scotty beam listens deezer listenbrainz --timestamp 1701872784
```
## Supported backends
### Supported backends
The following table lists the available backends and the currently supported features.
Backend | Listens Export | Listens Import | Loves Export | Loves Import
---------------|----------------|----------------|--------------|-------------
deezer | ✓ | ⨯ | ✓ | -
dump | ⨯ | ✓ | ⨯ | ✓
funkwhale | ✓ | ⨯ | ✓ | -
jspf | - | ✓ | - | ✓
lastfm | ✓ | ✓ | ✓ | ✓
@ -55,6 +130,8 @@ subsonic | ⨯ | ⨯ | ✓ | -
**✓** implemented **-** not yet implemented **⨯** unavailable / not planned
See the comments in [config.example.toml](./config.example.toml) for a description of each backend's available configuration options.
## Contribute
The source code for Scotty is available on [SourceHut](https://sr.ht/~phw/scotty/). To report issues or feature requests please [create a ticket](https://todo.sr.ht/~phw/scotty).

6
config.example.toml
View file

@ -71,7 +71,7 @@ identifier = ""
backend = "spotify"
# You need to register an application on https://developer.spotify.com/
# and set the client ID and client secret below.
# When registering use "http://127.0.0.1:2222/callback/spotify" as the
# When registering use "http://127.0.0.1:2369/callback/spotify" as the
# callback URI and enable "Web API".
client-id = ""
client-secret = ""
@ -81,7 +81,7 @@ client-secret = ""
backend = "deezer"
# You need to register an application on https://developers.deezer.com/myapps
# and set the client ID and client secret below.
# When registering use "http://127.0.0.1:2222/callback/deezer" as the
# When registering use "http://127.0.0.1:2369/callback/deezer" as the
# callback URI.
client-id = ""
client-secret = ""
@ -92,7 +92,7 @@ backend = "lastfm"
username = ""
# You need to register an application on https://www.last.fm/api/account/create
# and set the API ID and shared secret below.
# When registering use "http://127.0.0.1:2222/callback/lastfm" as the
# When registering use "http://127.0.0.1:2369/callback/lastfm" as the
# callback URI.
client-id = ""
client-secret = ""

8
internal/translations/README.md
View file

@ -18,15 +18,11 @@ After strings have been added or modified in the code or after changes have been
This requires the gotext tool to be installed:
```
go install golang.org/x/text/cmd/gotext@latest
```
go install golang.org/x/text/cmd/gotext@latest
The following command will extract all strings and merge the translations:
```
go generate ./internal/translations/translations.go
```
go generate ./internal/translations/translations.go
## License