sptlrx (https://github.com/raitonoberu/sptlrx)

Synchronized lyrics in your terminal

## Features

- Compatible with Spotify, MPD, Mopidy, MPRIS and browsers.
- Works well with long lines & Unicode characters.
- Easy to customize.
- Allows piping to stdout.
- Single binary & cross-plaftorm.

## Installation

**Linux**

- Arch Linux ([@BachoSeven](https://github.com/BachoSeven))

```sh
yay -S sptlrx-bin
```

- Debian / Ubuntu ([@mdosch](https://github.com/mdosch))

```sh
sudo apt install sptlrx
```

- NixOS ([@MoritzBoehme](https://github.com/MoritzBoehme))

```sh
nix-env -iA nixos.sptlrx
# or if using nixpkgs
nix-env -iA nixpkgs.sptlrx
```

**Windows**, **MacOS** & **Other**

Download the binary from the [Releases](https://github.com/raitonoberu/sptlrx/releases/latest) page or [build it yourself](./building.md).

## Configuration

Config file will be created at the first launch. On Linux it's located in `~/.config/sptlrx/config.yaml`. Run `sptlrx -h` to see the full path.

Show config contents (with descriptions)

```yaml
### Global settings ###
# Player that will be used. Possible values: spotify, mpd, mopidy, mpris.
player: spotify
# Whether to ignore errors instead of showing them.
ignoreErrors: true
# Interval of the internal timer. Determines how often the terminal will be updated.
timerInterval: 200
# Interval for checking the position. Doesn't really affect the precision.
updateInterval: 2000

### Style settings ###
style:
  # Horizontal alignment of lines. Possible values: left, center, right.
  hAlignment: center
  # Style of the lines before the current one.
  before:
    # The colors can be either in HEX format, or ANSI 0-255.
    background: ""
    foreground: ""
    bold: true
    italic: false
    underline: false
    strikethrough: false
    blink: false
    faint: false
  # Style of the current line.
  current:
    # The colors can be either in HEX format, or ANSI 0-255.
    background: ""
    foreground: ""
    bold: true
    italic: false
    underline: false
    strikethrough: false
    blink: false
    faint: false
  # Style of the lines after the current one.
  after:
    # The colors can be either in HEX format, or ANSI 0-255.
    background: ""
    foreground: ""
    bold: false
    italic: false
    underline: false
    strikethrough: false
    blink: false
    faint: true

### Pipe settings ###
pipe:
  # Maximum line length. 0 - unlimited.
  length: 0
  # How to handle overflowing strings. Possible values: word, none, ellipsis.
  overflow: word

### MPD settings ###
mpd:
  # MPD server address with port.
  address: 127.0.0.1:6600
  # MPD server password (if any).
  password: ""

### Mopidy settings ###
mopidy:
  # Mopidy server address with port.
  address: 127.0.0.1:6680

### MPRIS settings ###
mpris:
  # Whitelist of MPRIS players. First available is used if empty.
  players: []

### Browser extension settings ###
browser:
  # Port on which the server will be started.
  port: 8974

### Local lyrics source ###
local:
  # Folder for scanning .lrc files. Example: "~/Music".
  folder: ""
```


### Spotify

```yaml
# config.yaml
player: spotify
```

If you want to use Spotify as your player, you will need to log in first.

1. Go to [developer.spotify.com](https://developer.spotify.com/dashboard), create a new app, and set the redirect URI to `http://127.0.0.1:8888/callback`. Grab your Client ID and Client Secret.
2. Run `sptlrx login`. You can pass Client ID and Client Secret in one of three ways:
  - As environmental variables: `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`
  - As CLI parameters: `--client-id` and `--client-secret`
  - Interactively: run `sptlrx login` without providing credentials and you will be prompted to enter them
3. Spotify login page will open. Log in and wait for the success message.

You only need to do this once. Your credentials will then be saved to `$XDG_STATE_HOME/sptlrx/spotify-auth.json`.

### MPD

```yaml
# config.yaml
player: mpd
mpd:
  address: 127.0.0.1:6600
  password: ""
```

MPD server will be used as a player.

### Mopidy

```yaml
# config.yaml
player: mopidy
mopidy:
  address: 127.0.0.1:6680
```

Mopidy server will be used as a player.

### MPRIS

```yaml
# config.yaml
player: mpris
mpris:
  players: []
```

Linux only. System player that supports MPRIS protocol will be used. You can also specify a whitelist of players to use, example: `players: [rhythmbox, spotifyd, ncspot]`. Run `playerctl -l` to get the names.

### Browser

```yaml
# config.yaml
player: browser
browser:
  port: 8974
```

You need to install a [browser extension](https://wnp.keifufu.dev/extension/getting-started). If you don't change the default port, no further configuration is required. Otherwise, create a custom adapter in the extension settings. **You can only run one instance on one port.**

### Local

```yaml
# config.yaml
local:
  folder: ""
```

If you want to use your local collection of `.lrc` files to display lyrics, specify the folder to scan. The application will use files with the most similar name. All other lyrics sources will be disabled.

## Information

### Source

Primary source is [lrclib.net](https://lrclib.net). It is also possible to use local `.lrc` files.

### Piping

Run `sptlrx pipe` to start printing the current lines to stdout. This can be used in various status bars and other applications.

### Flags

You can pass flags to override the style parameters defined in the config. Example:

```sh
sptlrx --current "bold,#FFDFD3,#957DAD" --before "104,faint,italic" --after "104,faint"
```

List of allowed styles: `bold`, `italic`, `underline`, `strikethrough`, `blink`, `faint`. The colors can be either in HEX format, or ANSI 0-255. The first color represents the foreground, the second represents the background.

Run `sptlrx --help` to see all the flags.

## License

**MIT License**, see [LICENSE](./LICENSE) for additional information.
