Skip to content

feat: customization docs #104

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 117 additions & 0 deletions docs/advanced-usage/customization/addons.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
---
title: Addons
description: 🏠 How to locally Install addons directly in reach of Spicetify.
---

## Why install locally?
Some people prefer to install addons locally, this can be for a variety of reasons:

+ Locally installed addons don't need an internet connection.
+ The addon in question may not be available on Marketplace.
+ The potential security concerns of remotely loading code you can't see.
+ The ability to modify the source code for addons.
+ Or even just for potential debugging of errors.

No matter the reason, this is the method addons were intended to be used with spicetify and is the way many original maintainers prefer out of habit.


## Location

Spicetify will check for local addons in your <a href="./config-file#location" target="_self">**config directory**</a>, as well as your installation directory.

## Installation
:::tip

It is highly recommended to learn how the <a href="./config-file" target="_self">**config**</a> works when installing addons locally


:::

### Themes
#### Directory Format / Required Files
```
Spicetify/
└── Themes/
└── Theme-Name/
├── user.css
├── color.ini
├── theme.js (optional)
└── assets/* (optional)
```

#### Application
```bash
Spicetify config current_theme Theme-Name
Spicetify config color_scheme Scheme-Name (optional)
Spicetify apply
```

#### Removal
```bash
Spicetify config current_theme Theme-Name-
Spicetify config color_scheme Scheme-Name- (optional)
Spicetify apply
```

:::note

color.ini files are split up into sections, and each section has a [scheme-name] at the top; use this name when modifying your config.

:::

### Extensions

#### Directory Format / Required Files:
```
Spicetify/
└── Extensions/
├── Extension.js
└── *.js
```

#### Application
```bash
Spicetify config extensions Extension.js
Spicetify apply
```

#### Removal
```bash
Spicetify config extensions Extension.js-
Spicetify apply
```

:::note

Very few extensions will remote load their code, however most theme extensions will.

:::

### Custom Apps
#### Directory Format / Required Files
```
Spicetify/
└── CustomApps/
└── CustomApp-Name/
├── style.css
├── index.js
├── manifest.json
└── *.js
```

#### Application
```bash
Spicetify config custom_apps CustomApp-Name
Spicetify apply
```
#### Removal
```bash
Spicetify config custom_apps CustomApp-Name-
Spicetify apply
```

:::note

Custom Apps will always add a tab on the sidebar of Spotify matching its directory name.

:::
165 changes: 165 additions & 0 deletions docs/advanced-usage/customization/config-file.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
---
title: Config
description: 🦺 Learn how the config works and how to modify it.
---

Spicetify's config file is a text file that contains various settings that affect Spicetify's behavior.
You can modify the config file to customize your Spicetify installation according to your needs.

Spicetify reads the data in this file at injection, for backing up, and for dev commands like watch.
Spicetify cannot function without it and requires read/write permissions for it.

## Location

The config file is typically located in one of the following paths depending on your operating system:

| Platform | Path |
| ------------------- | ------------------------------------------ |
| **Windows** | `%appdata%\spicetify\config-xpui.ini` |
| **Linux**/**MacOS** | `~/.config/spicetify/config-xpui.ini` |

However, you can know specifically where it is with:

```
spicetify -c
```

Or, you can open the folder where it is located with:

```
spicetify config-dir
```

If the config file is not present in any of the above locations, run `spicetify` in a terminal to generate one.


## Using The Config
:::note

Please read [**this**](./addons.md) to learn where to download custom addons.

:::

### Modification

To modify the config file through the command line, use the `spicetify config` command followed by the name of the setting you want to modify and its value. The general format for the command is:

```bash
spicetify config <setting> <value>
```

For example, to set the color_scheme setting to Dark, run:
```bash
spicetify config color_scheme Dark
```

To remove themes, extensions, or custom apps through the command line you will need to follow the same format stated above + `-` after the `value` field:
```bash
spicetify config color_scheme Dark-
```

If these methods fail you can open the `config-xpui.ini` file in any text editor, and manually modify the values of each setting.
### Application

In an attempt to not hinder load times, Spicetify will not automatically load changes made to the config, you will need to manually apply any changes you make prior to loading Spotify with the command:
+ `spicetify apply`

If this is your first time using the config or this is a fresh install please run:
+ `spicetify backup apply`

## Available Settings
Here is a list of available settings contained within the config and what they do.

### String-based
`spotify_path` **Path to Spotify directory.**

`prefs_path`: **Path to Spotify's prefs file.**

`current_theme`: **Folder name of a theme - must be exact.**

`color_scheme`: **Color.ini section name - first section used if unset.**

`custom_apps`: **Folder name of a custom app - seperate each app with `|`.**

`extensions`: **File name of extension + `.js` - seperate each app with `|`.**

`version`: **Spotify version - e.g 1.2.8.923.g4f94bf0d.**

`with`: **Spicetify version - e.g 2.16.2.**

```
spotify_launch_flags -
Default: None
Description: Command-line flags used when launching/restarting Spotify.
Docs: https://spicetify.app/docs/development/spotify-cli-flags
```

### Boolean-based
A boolean based setting accepts a 1 or a 0 inplace of a string.

```
inject_css -
Default: 1.
Description: Inject user.css from the theme folder of currently applied theme.
```
```
replace_colors -
Default: 1.
Description: Inject color.ini from the theme folder of currently applied theme,
which overwrites spotifys default css color variables.
```
```
disable_sentry -
Default: 1.
Description: Prevents Sentry and Amazon Qualaroo to send console log/error/warning to Spotify developers.
```
```
disable_ui_logging -
Default: 1.
Description: Stop logging of element clicks and scrolls.
```
```
remove_rtl_rule -
Default: 1.
Description: Removes obsolete CSS rules for Right-To-Left languages to improve render speed,
disable if you arent using a Left-To-Right language.
```
```
expose_apis -
Default: 1.
Description: Exposes Spotify's API, functions, and objects for use with Spicetify addons.
```
```
disable_upgrade_check -
Default: 1.
Description: Prevent Spotify checking new version and visually notifying user.
```
```
experimental_features -
Default: 1.
Description: Expose and add the ability to enable unreleased Spotify features,
"Experimental Features" on Profile menu.
```
```
home_config -
Default: 1.
Description: Enable the ability to re-arrange sections in Home page,
"Home config" on Profile menu.
```
```
sidebar_config -
Default: 1.
Description: Enable ability to stick, hide, re-arrange sidebar items,
"Sidebar config" on Profile menu.
```

```
check_spicetify_upgrade -
Default: 0.
Description: Notify the user whenever there is new Spicetify release.
```
```
overwrite_assets -
Default: 1.
Description: Themes that contain an assets folder will have its contents overwrite matching files in Spotifys xpui folder.
```
88 changes: 88 additions & 0 deletions docs/advanced-usage/customization/marketplace.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
---
title: Marketplace
description: 📶 Inject addons from within Spotify!
---

Marketplace is a custom app that offers a dedicated page within Spotify, allowing users to peruse and apply addons created by the community. The application facilitates the installation of themes, extensions, and snippets, with the exception of custom apps.

## Why use it?

<details>
<summary>Positives</summary>

1. Huge repository of addons.

2. Installation is quick and hassle-free.

3. Perfect for the average user who doesn't have time to waste in the terminal.

4. Change colour schemes in-app.

5. Since addons are fetched remotely, they will always be up to date.

6. Reduces user error.

</details>

<details>
<summary>Negatives</summary>

1. Fresh installs of Spotify / incorrect updating can cause Marketplace to forget your installed addons.

2. Marketplace requires internet connection to apply the addons.

3. Inability to modify addons' source code.

4. Inability to see what addons do at a code level before installing.

5. Relies on an active connection to GitHub (and jsdelivr for extensions).

</details>

## Installation

### Windows
#### Powershell
```powershell
Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/spicetify/spicetify-marketplace/main/resources/install.ps1" | Invoke-Expression
```

### Linux/MacOS
#### Shell
```bash
curl -fsSL https://raw.githubusercontent.com/spicetify/spicetify-marketplace/main/resources/install.sh | sh
```


## Reset Marketplace {#reset}
### Command
```
Marketplace.reset(theme, extensions, snippets) -
Description: Resets localstorage objects for specific addon types.
Parameters:
- none: Resets all Marketplace localstorage items.
- theme (optional): Reset the current theme installed by Marketplace.
- extensions (optional): Reset all extensions installed by Marketplace.
- snippets (optional): Reset all snippets.
Usage: `Marketplace.reset("theme", "extensions")` or `Marketplace.reset()`
```
### Guide
In the event you cannot access Marketplaces settings menu, you will need to run this command in terminal:

```bash
spicetify enable-devtools
```

Once spotify has opened, press <kbd>CTRL</kbd> <kbd>SHIFT</kbd> <kbd>I</kbd> / <kbd>CMD</kbd> <kbd>OPTION</kbd> <kbd>I</kbd> to bring up devtools, and navigate to the console tab:

<details>
<summary>Example Image</summary>
<img src="https://i.imgur.com/UKnWDUs.png"></img>
</details>

Once in the console tab, type in `Marketplace.reset()` + optional args and press enter:

<details>
<summary>Example Image</summary>
<img src="https://i.imgur.com/eXYEyUp.png"></img>
</details>
56 changes: 1 addition & 55 deletions docs/faq.md
Original file line number Diff line number Diff line change
@@ -4,30 +4,7 @@ title: FAQ

## Where is the config file?

The config file is generally located at:

| Platform | Path |
| ------------------- | ------------------------------------------ |
| **Windows** | `%appdata%\spicetify\config-xpui.ini` |
| **Linux**/**macOS** | `~/.config/spicetify/config-xpui.ini` |

However, you can know specifically where it is with:

```
spicetify -c
```

Or, you can open the folder where it is located by entering the following in your terminal:

```
spicetify config-dir
```

For detail information of each config field, please run:

```bash
spicetify --help config
```
You can learn about the config file and where its located <a href="./advanced-usage/customization/config-file#location" target="_self">**here**</a>.

## Cannot find `pref_file`

@@ -57,34 +34,3 @@ Delete all files in the following folder and launch spotify again.
- **Windows**: `%LOCALAPPDATA%\Spotify`
- **Linux**: `~/.config/spotify`
- **macOS**: `~/Library/Application Support/Spotify`

## Sometimes **Popup Lyrics** and/or **Lyrics Plus** seem to not work

This problem happens in the extension [Popup Lyrics](https://github.com/spicetify/spicetify-cli/wiki/Extensions#pop-up-lyrics) and custom app [Lyrics Plus](https://github.com/spicetify/spicetify-cli/wiki/Custom-Apps#lyrics-plus) mostly because your Musixmatch token has been flagged for doing too many requests. This can be fixed by just waiting without skipping songs too much, however, if it is still a problem for you, all you need to do is to install the Musixmatch official app, which is a web-based app like Spotify.

1. **Linux:** find an archive online
**Windows:** go to [store.rg-adguard.net](https://store.rg-adguard.net/) and then select ProductID and enter `9wzdncrfj235` and click done. Download the .appxbundle and install.

2. **You don't need to log in!**

3. Now in Musixmatch app, hit `Ctrl + Shift + i` to bring up DevTools.

![mxm1](https://i.imgur.com/jMGMgCc.png)

4. Switch to Network tab. Hit `Ctrl + R`. Filter results with "apic":

![mxm2](https://i.imgur.com/QdwqtQa.png)

5. Click on any result. Click on the Headers tab. Scroll all the way down. Note down `usertoken`

![mxm3](https://i.imgur.com/ZsGwKG3.png)

It should look like this:

```
200501593b603a3fdc5c9b4a696389f6589dd988e5a1cf02dfdce1
```

6. You can open the config for Popup Lyrics by right clicking on the Popup Lyrics button. Or if you're using Lyrics Plus, open the config by clicking on Lyrics in the sidebar and clicking on the profile menu and then clicking 'Lyrics Plus config'. You can then paste your personal token in the input field in the Musixmatch section and turn the switch on.

![mxm4](https://i.imgur.com/yvrkllb.png)
14 changes: 14 additions & 0 deletions sidebars.js
Original file line number Diff line number Diff line change
@@ -31,6 +31,20 @@ const sidebars = {
'advanced-usage/themes',
'advanced-usage/extensions',
'advanced-usage/custom-apps',
{
type: 'category',
label: 'Customization',
link: {
type: 'generated-index',
description: 'How to customize Spicetify to fit your needs.',
slug: 'advanced-usage/customization',
},
items: [
'advanced-usage/customization/config-file',
'advanced-usage/customization/addons',
'advanced-usage/customization/marketplace',
],
},
],
},
{