diff --git a/docs/advanced-usage/command-line-interface.md b/docs/advanced-usage/command-line-interface.md deleted file mode 100644 index 6027eec7..00000000 --- a/docs/advanced-usage/command-line-interface.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Command Line Interface (CLI) -description: πŸ‘Ύ Using Spicetify from the command line. ---- - -Run with no command once to generate config file - -```bash -spicetify -``` - -If you just want to use Custom Apps and Extensions head over to each specific section, if you want to create your own theme, keep reading below. - -Make sure config file is created successfully and there is no error, then run: - -```bash -spicetify backup apply enable-devtools -``` - -From now, after changing colors in `color.ini` or CSS in `user.css`, you just need to run: - -```bash -spicetify update -``` - -to update your theme. - -In Spotify, hit Ctrl Shift R / Command Shift R to reload and receive visual update of your theme. - -For other commands and additional flags information, please run: - -```bash -spicetify --help -``` diff --git a/docs/advanced-usage/custom-apps.md b/docs/advanced-usage/custom-apps.md deleted file mode 100644 index 81ad59db..00000000 --- a/docs/advanced-usage/custom-apps.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Custom Apps -description: πŸ’₯ Manually installing Custom Apps. ---- - -Custom Apps, similar to Extensions, are simply Javascript that will be injected into Spotify, that consists of a page that can be accessed from the sidebar. - -## Installing - -Custom Apps files can be stored in: - -- `CustomApps` folder in Home directory: - -| Platform | Path | -| ------------------- | -------------------------------------- | -| **Windows** | `%appdata%\spicetify\CustomApps\` | -| **Linux**/**MacOS** | `~/.config/spicetify/CustomApps` | - -- `CustomApps` folder in Spicetify executable directory. - -If there are 2 Custom Apps with the same name, the extension within the Home directory will be prioritized. - -After placing the Custom App file into correct folder, run following command to install it: - -```bash -spicetify config custom_apps -spicetify apply -``` - -**Note:** Using `config` command to add Custom Apps always append file name to existed extensions list. It does not replace the whole key's value. - -## Uninstalling - -If you want to remove a custom app from the current list of custom apps you can always append a `-` after the file name: - -```bash -spicetify config custom_apps - -spicetify apply -``` - -## Custom Apps - -Inject custom apps to Spotify and access them in left sidebar. -Add your desired custom app folder names in config, separated them by `|` character. -Example: - -```ini -[AdditionalOptions] -... -custom_apps = reddit|yourownapp -``` - -App folders can be stored in: - -- `CustomApps` folder in Home directory: - -| Platform | Path | -| ------------------- | -------------------------------------- | -| **Windows** | `%appdata%\spicetify\CustomApps\` | -| **Linux**/**MacOS** | `~/.config/spicetify/CustomApps` | - -- `CustomApps` folder in Spicetify executable directory. - -If there are 2 apps having same name, app in Home directory is prioritized. - -Three apps have been included to demonstrate how to create and inject an app: - -- [Reddit](#reddit) -- [New Releases](#new-releases) -- [Lyrics Plus](#lyrics-plus) - -### Reddit - -Fetching posts from any Spotify link sharing subreddit. You can add, remove, arrange subreddits and customize post visual in config menu (in Profile menu, top right button with your username). - -![Reddit](/images/apps/reddit.png) - -To install, run following commands: - -``` -spicetify config custom_apps reddit -spicetify apply -``` - -### New Releases - -Aggregate all new releases from favorite artists, podcasts. Time range, release type, and other filters can be customized in config menu (in Profile menu, top right button with your username). Date format is based on your locale code (BCP47). - -![New Releases](/images/apps/new-releases.png) - -To install, run following commands: - -``` -spicetify config custom_apps new-releases -spicetify apply -``` - -### Lyrics Plus - -Get access to the current track's lyrics from various lyrics providers (Musixmatch, Netease, LRCLIB). Learn more [here](https://github.com/spicetify/cli/tree/main/CustomApps/lyrics-plus). - -Colors, lyrics providers can be customized in config menu (in Profile menu, top right button with your username). - -![Lyrics Plus](/images/apps/lyrics-plus.png) - -To install, run following commands: - -``` -spicetify config custom_apps lyrics-plus -spicetify apply -``` diff --git a/docs/advanced-usage/extensions.md b/docs/advanced-usage/extensions.md deleted file mode 100644 index 03159b4b..00000000 --- a/docs/advanced-usage/extensions.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: Extensions -description: 🧩 Manually installing Extensions. ---- - -Extensions, in a nutshell, are JavaScript files that will be evaluated along with Spotify main JavaScript. - -## Installing - -Extension files can be stored in: - -- `Extensions` folder in Home directory: - -| Platform | Path | -| ------------------- | -------------------------------------- | -| **Windows** | `%appdata%\spicetify\Extensions\` | -| **Linux**/**MacOS** | `~/.config/spicetify/Extensions` | - -- `Extensions` folder in Spicetify executable directory. - -If there are 2 extensions with the same name, the extension within the Home directory will be prioritized. - -Some Spotify API endpoints are exposed and can be found in the global object `Spicetify`. Check out `global.d.ts` for API documentation. - -After placing the extension file into correct folder, run following command to install it: - -```bash -spicetify config extensions -spicetify apply -``` - -**Note:** Using `config` command to add extension always append file name to existed extensions list. It does not replace the whole key's value. - -## Uninstalling - -If you want to remove an extension from the current list of extensions you can always append a `-` after the file name: - -```bash -spicetify config extensions - -spicetify apply -``` - -## Manual Install - -You can always manually edit the config file, add your desired extension filenames in `extensions` key, separated them by `|` character. -Example: - -```ini -[AdditionalOptions] -... -extensions = autoSkipExplicit.js|queueAll.js|djMode.js|shuffle+.js|trashbin.js -``` - -Afterwards, you will need to run the following: - -``` -spicetify apply -``` - -## Extensions - -Below are list of default extensions that come with the distributed package: - -- [Auto Skip Videos](#auto-skip-videos) -- [Bookmark](#bookmark) -- [Christian Spotify](#christian-spotify) -- [Full App Display](#full-app-display) -- [Keyboard Shortcut](#keyboard-shortcut) -- [Loopy Loop](#loopy-loop) -- [Pop-up Lyrics](#pop-up-lyrics) -- [Shuffle+](#shuffle) -- [Trash Bin](#trash-bin) -- [Web Now Playing](#web-now-playing) - -### Auto Skip Videos - -**Filename:** `autoSkipVideo.js` - -Videos are unable to play in some regions because of Spotify's policy. Instead of jumping to next song in playlist, it just stops playing. And it's kinda annoying to open up the client to manually click next every times it happens. Use this extension to skip them automatically. - -### Bookmark - -**Filename:** `bookmark.js` - -Easily store and browse pages, play tracks or tracks in specific time. Useful for who wants to check out an artist, album later without following them or writing their name down. - -![Ext_bookmark](/images/extensions/bookmark.png) - -### Christian Spotify - -**Filename:** `autoSkipExplicit.js` - -Auto skip explicit tracks. Toggle option is in Profile menu (top right button). - -![Ext_ChristianDemo](/images/extensions/christian-demo.png) - -### Full App Display - -**Filename:** `fullAppDisplay.js` - -Full App Display: Minimal album cover art display with beautiful blur effect background. Activating button located in top bar. While in display mode, double click anywhere to exit. Right click anywhere to open setting menu. - -![Ext_FAD](/images/extensions/full-app-display.png) - -### Keyboard Shortcut - -**Filename:** `keyboardShortcut.js` - -Extends Spotify's default keybinds (toggle help modal with `?`) with vim like shortcuts. Less time touching the mouse. - -- Ctrl Tab / Ctrl Shift Tab: Navigate items in left sidebar menu. -- PageUp/PageDown: Force scroll up/down app page only (because mouse focus is sometimes in sidebar region and they scroll sidebar instead of app page). -- J/K: Scroll app page up/down. \*Tips hat to Vim users\* -- G/Shift G: Scroll to top or bottom -- F: Open up keyboard-driven navigation. Hit correct key sequences to open up place you want to go: - -![KeyboardDemo](/images/extensions/keyboard-demo.png) - -### Loopy Loop - -**Filename:** `loopyLoop.js` - -Provide ability to mark start and end points on progress bar and automatically loop over that track portion. - -![LoopyLoop](/images/extensions/loopy-loop.png) - -### Pop-up Lyrics - -**Filename:** `popupLyrics.js` - -Have easy access to a pop-up window with the current song's lyrics. Click at microphone icon on top bar to open lyrics windows. Right click at the same icon to open config menu to customize looks and lyrics providers priorities. - -![Pop-up Lyrics](/images/extensions/popup-lyrics.png) - -### Shuffle+ - -**Filename:** `shuffle+.js` -Shuffles using Fisher–Yates algorithm with zero bias. After installing extensions, right click album/playlist/artist item, there will be an option "Play with Shuffle+". You can also multiple select tracks and choose to "Play with Shuffle+". - -![Shuffle](/images/extensions/shuffle.png) - -### Trash Bin - -**Filename:** `trashbin.js` -Throw songs/artists to trash bin and never hear them again (automatically skip). This extension will append a Throw to Trashbin option in tracks and artists link right click menu. - -![Ext_Trash](/images/extensions/trash.png) - -### Web Now Playing - -**Filename:** `webnowplaying.js` -For Rainmeter users, establish connection with WebNowPlaying plugin to send track metadata and control players. - -If you just want WebNowPlaying without changing UI color, CSS, run this: - -```powershell -spicetify config inject_css 0 replace_colors 0 -spicetify config extensions webnowplaying.js -spicetify apply -``` - -## Legacy Extensions - -If you are running Spicetify 1.2.1 or below, and a supported Spotify version, you may also have access to the extensions listed below. - -- [DJ Mode](#dj-mode) -- [New Release](#new-release) -- [Queue All](#queue-all) - -### DJ Mode - -**Filename:** `djMode.js` - -Easily setting up the client for your friends or audiences to choose, add song to queue but prevent them to control player. Plays button in album track list/playlist are re-purposed to add track to queue, instead of play track directly. Hide Controls option also allow you to hide all control button in player bar, Play/More/Follow buttons in cards. - -![Ext_DJDemo](/images/extensions/dj-demo.png) - -### New Release - -**Filename:** `newRelease.js` - -Aggregate all new releases from favorite artists, podcasts. Setting menu could be opened by right clicking at Bell icon. - -![Ext_newrelease](https://user-images.githubusercontent.com/26436809/86569793-50dd8480-bfb2-11ea-8d82-be238d719660.png) - -### Queue All - -**Filename:** `queueAll.js` - -You like using Discover, New Releases page to find new music but adding each one of them to queue takes a lot of effort? If so, activate this extensions and apply. At top of every carousel now has a "Queue All" button to help you add all of them to queue. Note: Not available for playlist carousels. Just songs, albums ones. - -![QueueAllDemo](/images/extensions/queue-all-demo.png) diff --git a/docs/advanced-usage/index.md b/docs/advanced-usage/index.md deleted file mode 100644 index 4c5d240f..00000000 --- a/docs/advanced-usage/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Getting Started ---- - -```mdx-code-block -import DocCardList from '@theme/DocCardList'; -import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; - - -``` \ No newline at end of file diff --git a/docs/advanced-usage/installation.md b/docs/advanced-usage/installation.md deleted file mode 100644 index 0add04ed..00000000 --- a/docs/advanced-usage/installation.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Installation -description: ⚑ An advanced view on how to install Spicetify. ---- - -## Windows - -### Powershell (pre-built binary) - Recommended - -```powershell -iwr -useb https://raw.githubusercontent.com/spicetify/cli/main/install.ps1 | iex -``` - -### Chocolatey - -Follow this guide: https://chocolatey.org/packages/spicetify-cli - -### Scoop - -```powershell -scoop install spicetify-cli -``` - -#### Spotify installed from Scoop - -- To find the location of your Spotify installation, run `scoop prefix spotify`. - -```console -$ scoop prefix spotify -C:\Users\\scoop\apps\spotify\current -``` - -After you have located it, set `spotify_path` to that directory in Spicetify's config file: - -![scoop-spotify-path](https://user-images.githubusercontent.com/56180050/158084602-99428adf-93bb-4983-968f-14e1f4f5b253.png) - -### Winget - -```powershell -winget install Spicetify.Spicetify -``` - -## Linux and MacOS - -### Shell (pre-built binary) - Recommended - -```bash -curl -fsSL https://raw.githubusercontent.com/spicetify/cli/main/install.sh | sh -``` - -### Homebrew or LinuxBrew - -```bash -brew install spicetify-cli -``` - -On macOS, you will need to set `spotify_path` to `/Applications/Spotify.app/Contents/Resources` in the `~/.config/spicetify/config-xpui.ini` config file. - -### AUR - -```bash -yay -S spicetify-cli -``` - -### Note for Linux users - -#### Spotify installed from AUR - -Before applying Spicetify, you need to gain write permission on Spotify files, by running command: - -```bash -sudo chmod a+wr /opt/spotify -sudo chmod a+wr /opt/spotify/Apps -R -``` - -**Note:** Your Spotify client location might be different. - -#### Spotify installed via `spotify-launcher` package (Arch Linux) - -If Spotify is installed through the `spotify-launcher` package, then Spotify won't install to `/opt/spotify` and is instead in this folder: `$HOME/.local/share/spotify-launcher/install/usr/share/spotify/` - -This directory will need to be added to the `spotify-path` section of the config (and you won't need to change any permissions like the AUR method). - -**Note:** `spotify-path` must be an absolute path. Do not use `~` to reference the home folder. - -#### Spotify installed from Snap - -Apps installed from Snap **cannot be modified** so you need to follow these steps to get Spicetify working: - -1. Uninstall Spotify in Snap or run command `snap remove spotify` -2. Install Spotify using `apt`: - -```sh -curl -sS https://download.spotify.com/debian/pubkey_C85668DF69375001.gpg | sudo gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/spotify.gpg -echo "deb http://repository.spotify.com stable non-free" | sudo tee /etc/apt/sources.list.d/spotify.list -sudo apt-get update && sudo apt-get install spotify-client -``` - -3. After Spotify is installed successfully, you need to gain read write permissions on Spotify files, by running commands: - -```bash -sudo chmod a+wr /usr/share/spotify -sudo chmod a+wr /usr/share/spotify/Apps -R -``` - -**Note:** Your Spotify client location might be different. - -#### Spotify installed from Flatpak - -- You need to find where Flatpak stores your Spotify client. In Manjaro and Fedora, it is stored in: - -``` -/var/lib/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify/ -``` - -- In some distros it is stored in: -``` -~/.local/share/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify/ -``` - -- Yours might be different, try these steps: - -1. Find flatpak installation place with command: `flatpak --installations` -2. Go to that directory and dig in until you find folder which contain items like these: - -![flat2](https://user-images.githubusercontent.com/26436809/57563050-81408780-73dc-11e9-92e8-d0cc60502ff3.png) - -After you have Spotify location, set `spotify_path` in config file to that directory: - -![flat2](https://user-images.githubusercontent.com/26436809/57563057-9ddcbf80-73dc-11e9-82d8-d31cdf7e9cef.png) - -3. Find your `prefs` file: - It could be either in these two locations: - -- `~/.config/spotify/prefs` -- `~/.var/app/com.spotify.Client/config/spotify/prefs` - -Check both, expand the right one to absolute path and set it to `prefs_path` in config file. - -```bash -spicetify config prefs_path ~/.var/app/com.spotify.Client/config/spotify/prefs -``` - -4. Finally in terminal, set read/write permission for it: - -```bash -sudo chmod a+wr /var/lib/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify -sudo chmod a+wr -R /var/lib/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify/Apps -``` - -## Legacy Installations - -If, for some reason, you are not using the most up to date Spotify client, you may need to install a specific version of Spicetify. -This is not recommended as our prime focus will always be the latest Spotify version. - -As such, you will need to run either of the below commands with the desired version. -If you wish to use old Spotify client v1.1.56 or older, you have to install spicetify v1.2.1. - -**Windows**: In powershell - -```powershell -$v="1.2.1"; Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/spicetify/cli/main/install.ps1" | Invoke-Expression -``` - -**Linux/MacOS:** In bash - -```bash -curl -fsSL https://raw.githubusercontent.com/spicetify/cli/main/install.sh -o /tmp/install.sh -sh /tmp/install.sh 1.2.1 -``` - -spicetify v1 code is available in branch [`legacy`](https://github.com/spicetify/cli/tree/legacy) if you want to build from source. - -If you want legacy themes, you can find them [here](https://github.com/spicetify/spicetify-themes/tree/legacy). diff --git a/docs/advanced-usage/themes.md b/docs/advanced-usage/themes.md deleted file mode 100644 index 1b7873ca..00000000 --- a/docs/advanced-usage/themes.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Themes -description: ✨ Themes for Spicetify. ---- - -One of the most popular features in Spicetify is theming. -You can customize your Spotify to your **heart's** desire! -**However**, this is a very cumbersome task. - -For this reason, the theming heroes of the Spicetify community have created a huge library of themes which can be found in the following repositories: - -1. [spicetify/spicetify-themes](https://github.com/spicetify/spicetify-themes) - The official Spicetify themes repository. Feel free to contribute with more themes! -2. [NYRI4/Comfy-spicetify](https://github.com/NYRI4/Comfy-spicetify) -3. [williamckha/spicetify-fluent](https://github.com/williamckha/spicetify-fluent) -4. [Catppuccin/spicetify](https://github.com/catppuccin/spicetify) -5. [nimsandu/spicetify-bloom](https://github.com/nimsandu/spicetify-bloom) -6. [Tetrax-10/Nord-Spotify](https://github.com/Tetrax-10/Nord-Spotify) (not maintained) -7. [JulienMaille/dribbblish-dynamic-theme](https://github.com/JulienMaille/dribbblish-dynamic-theme) (not maintained) -8. [sanoojes/spicetify-lucid](https://github.com/sanoojes/spicetify-lucid) -9. [Skaytacium/Gruvify](https://github.com/Skaytacium/Gruvify) -10. [dracula/spicetify](https://github.com/dracula/spicetify) (not maintained) -11. [Spotify Dark](https://github.com/SyndiShanX/Spotify-Dark) -12. [bluedrift/Spicetify-Throwback](https://github.com/bluedrift/Spicetify-Throwback) -13. [m0squdev/dracula-spicetify-theme](https://github.com/m0squdev/dracula-spicetify-theme) -14. [Adrien5902/SpicetifyCat](https://github.com/Adrien5902/SpicetifyCat) -15. [RetroPlayer](https://github.com/Seglats/Spicetify-retro) -16. Insert your theme here! diff --git a/docs/advanced-usage/uninstallation.md b/docs/advanced-usage/uninstallation.md deleted file mode 100644 index 81e17e8f..00000000 --- a/docs/advanced-usage/uninstallation.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Uninstallation -description: πŸ—‘ How to remove Spicetify. ---- - -## Windows - -### Powershell -```cmd -spicetify restore -rmdir -r -fo $env:APPDATA\spicetify -rmdir -r -fo $env:LOCALAPPDATA\spicetify -``` - -## Linux and MacOS - -:::note - -If you used a package manager to install Spicetify, please use its default methods for removing packages. - -::: - -### Shell -```bash -spicetify restore -rm -rf ~/.spicetify -rm -rf ~/.config/spicetify -``` diff --git a/docs/cli/commands.md b/docs/cli/commands.md new file mode 100644 index 00000000..c82ebab7 --- /dev/null +++ b/docs/cli/commands.md @@ -0,0 +1,278 @@ +--- +title: Commands +description: Complete Spicetify command reference. +--- + +This page documents all Spicetify CLI commands. + +## Core Commands + +### `spicetify` (no arguments) + +Run with no arguments to generate the config file on first run, or verify your setup. + +```bash +spicetify +``` + +### `backup` + +Create a backup of vanilla Spotify files. Required before applying Spicetify for the first time. + +```bash +spicetify backup +``` + +### `apply` + +Apply Spicetify modifications to Spotify. + +```bash +spicetify apply +``` + +This injects your theme, extensions, custom apps, and other modifications into Spotify. + +### `restore` + +Remove all Spicetify modifications and restore Spotify to vanilla state. + +```bash +spicetify restore +``` + +Your config file and customization files are preserved. + +### `update` + +Hot-reload theme changes without full restart. Use this during theme development. + +```bash +spicetify update +``` + +After running, press Ctrl + Shift + R (or Cmd + Shift + R on macOS) in Spotify to see changes. + +### `upgrade` + +Upgrade Spicetify to the latest version (only works with script-based installations). + +```bash +spicetify upgrade +``` + +--- + +## Configuration Commands + +### `config` + +View or modify configuration values. + +**View all settings:** + +```bash +spicetify config +``` + +**View a specific setting:** + +```bash +spicetify config current_theme +``` + +**Set a value:** + +```bash +spicetify config current_theme Sleek +``` + +**Set multiple values:** + +```bash +spicetify config current_theme Sleek color_scheme Dark +``` + +**Add to a list (extensions, custom_apps):** + +```bash +spicetify config extensions fullAppDisplay.js +``` + +This appends to existing extensions, not replaces. + +**Remove from a list:** + +```bash +spicetify config extensions fullAppDisplay.js- +``` + +Note the trailing `-`. + +### `config-dir` + +Open the Spicetify config directory in your file manager. + +```bash +spicetify config-dir +``` + +### `-c` / `--config` + +Print the config file path. + +```bash +spicetify -c +``` + +--- + +## Utility Commands + +### `enable-devtools` + +Enable Chromium DevTools in Spotify. Useful for debugging themes and extensions. + +```bash +spicetify enable-devtools +``` + +Access DevTools with Ctrl + Shift + I. + +### `watch` + +Watch for theme changes and auto-apply. Useful during development. + +```bash +spicetify watch +``` + +Monitors `color.ini` and `user.css` in your current theme folder. + +### `path` + +Print various Spicetify-related paths. + +```bash +spicetify path +spicetify path userdata # Config directory +spicetify path spotify # Spotify installation +``` + +### `auto` + +Automatically backup (if needed) and apply, then launch Spotify. + +```bash +spicetify auto +``` + +Useful as a shortcut target instead of the Spotify executable. + +--- + +## Combined Commands + +Commands can be combined in a single call: + +```bash +# First-time setup +spicetify backup apply enable-devtools + +# After Spotify updates +spicetify backup apply + +# Full restore and reapply +spicetify restore backup apply +``` + +--- + +## Flags + +### `--help` / `-h` + +Show help for a command. + +```bash +spicetify --help +spicetify --help config +``` + +### `--version` / `-v` + +Show Spicetify version. + +```bash +spicetify --version +``` + +### `--no-restart` + +Apply changes without restarting Spotify. + +```bash +spicetify apply --no-restart +``` + +### `--quiet` / `-q` + +Suppress non-error output. + +```bash +spicetify apply -q +``` + +### `--extension` / `-e` + +Specify a single extension to apply (useful for testing). + +```bash +spicetify apply -e myExtension.js +``` + +--- + +## Examples + +### Fresh Install Workflow + +```bash +# Install Spicetify (see Installation page) +# Generate config +spicetify + +# First-time setup +spicetify backup apply enable-devtools +``` + +### Enable an Extension + +```bash +spicetify config extensions fullAppDisplay.js +spicetify apply +``` + +### Change Theme + +```bash +spicetify config current_theme Sleek color_scheme Dark +spicetify apply +``` + +### After Spotify Updates + +```bash +spicetify backup apply +``` + +### Theme Development + +```bash +# One-time: apply your theme +spicetify config current_theme MyTheme +spicetify apply + +# During development: watch for changes +spicetify watch +``` diff --git a/docs/cli/index.md b/docs/cli/index.md new file mode 100644 index 00000000..66d10a51 --- /dev/null +++ b/docs/cli/index.md @@ -0,0 +1,36 @@ +--- +title: CLI Reference +description: Command-line interface reference for Spicetify. +--- + +Spicetify is primarily a command-line tool. This section covers the command reference. + +## Quick Start + +After [installing Spicetify](/docs/getting-started), the basic workflow is: + +```bash +# Generate config (first run only) +spicetify + +# Backup Spotify and apply Spicetify +spicetify backup apply + +# After making changes, apply them +spicetify apply +``` + +## Getting Help + +For help on any command: + +```bash +spicetify --help +spicetify --help +``` + +Example: + +```bash +spicetify --help config +``` diff --git a/docs/customization/config-file.md b/docs/customization/config-file.md new file mode 100644 index 00000000..9e0e68b2 --- /dev/null +++ b/docs/customization/config-file.md @@ -0,0 +1,165 @@ +--- +title: Configuration Reference +description: Complete reference for Spicetify's config file. +--- + +Spicetify stores its configuration in `config-xpui.ini`. This page documents all available options. + +## File Location + +| Platform | Path | +|----------|------| +| **Windows** | `%appdata%\spicetify\config-xpui.ini` | +| **Linux / macOS** | `~/.config/spicetify/config-xpui.ini` | + +To find the exact path: + +```bash +spicetify -c +``` + +To open the config folder: + +```bash +spicetify config-dir +``` + +## Editing Configuration + +### Via CLI (Recommended) + +```bash +spicetify config +spicetify apply +``` + +Examples: + +```bash +# Set a theme +spicetify config current_theme Sleek + +# Add an extension +spicetify config extensions fullAppDisplay.js + +# Remove an extension (note the trailing -) +spicetify config extensions fullAppDisplay.js- + +# Set multiple values at once +spicetify config current_theme Sleek color_scheme Dark +``` + +### Via Direct File Editing + +Open `config-xpui.ini` in any text editor, make changes, save, then run: + +```bash +spicetify apply +``` + +--- + +## Configuration Sections + +### [Setting] + +Core paths and settings. + +| Key | Description | Example | +|-----|-------------|---------| +| `spotify_path` | Path to Spotify installation | `/opt/spotify` | +| `prefs_path` | Path to Spotify's `prefs` file | `~/.config/spotify/prefs` | +| `spotify_launch_flags` | Flags passed when launching Spotify | `--remote-debugging-port=9222` | +| `check_spicetify_upgrade` | Check for Spicetify updates on startup | `1` (enabled) | + +### [Preprocesses] + +Control CSS/color injection. + +| Key | Description | Default | +|-----|-------------|---------| +| `disable_sentry` | Disable Spotify's error reporting | `1` | +| `disable_ui_logging` | Disable UI telemetry | `1` | +| `remove_rtl_rule` | Remove right-to-left CSS rules | `1` | +| `expose_apis` | Expose Spicetify APIs to extensions | `1` | + +### [AdditionalOptions] + +Theme and add-on configuration. + +| Key | Description | Example | +|-----|-------------|---------| +| `current_theme` | Active theme folder name | `Sleek` | +| `color_scheme` | Color scheme within current theme | `Dark` | +| `extensions` | Enabled extensions (pipe-separated) | `fullAppDisplay.js\|trashbin.js` | +| `custom_apps` | Enabled custom apps (pipe-separated) | `reddit\|lyrics-plus` | +| `inject_css` | Inject theme CSS | `1` | +| `inject_theme_js` | Inject theme JavaScript (if present) | `1` | +| `replace_colors` | Apply theme colors | `1` | +| `overwrite_assets` | Allow themes to replace assets | `0` | +| `sidebar_config` | Sidebar customization (auto-generated) | - | +| `home_config` | Homepage customization (auto-generated) | - | + +### [Patch] + +Low-level patches. Usually leave these alone. + +| Key | Description | Default | +|-----|-------------|---------| +| `xpui.js_find_8008` | Enable specific patching | Varies | +| `xpui.js_repl_8008` | Replacement value for patch | Varies | + +--- + +## Common Tasks + +### See All Current Settings + +```bash +spicetify config +``` + +### Reset to Defaults + +```bash +spicetify restore +``` + +This removes Spicetify modifications from Spotify but keeps your config file. + +### Backup Current State + +```bash +spicetify backup +``` + +Creates a backup of vanilla Spotify that can be restored later. + +### Full Reset + +To completely start fresh: + +```bash +spicetify restore +rm ~/.config/spicetify/config-xpui.ini # Linux/macOS +# or on Windows: del %appdata%\spicetify\config-xpui.ini +spicetify +``` + +Running `spicetify` with no config file regenerates the default configuration. + +--- + +## Getting Help + +For detailed help on any config option: + +```bash +spicetify --help config +``` + +For all available commands: + +```bash +spicetify --help +``` diff --git a/docs/customization/custom-apps.md b/docs/customization/custom-apps.md new file mode 100644 index 00000000..d192d0df --- /dev/null +++ b/docs/customization/custom-apps.md @@ -0,0 +1,158 @@ +--- +title: Custom Apps +description: Add new pages to Spotify's sidebar with custom apps. +--- + +Custom Apps are JavaScript applications that add entirely new pages to Spotify's sidebar. Unlike extensions (which modify existing behavior), custom apps create standalone experiences within Spotify. + +## Installing Custom Apps + +### Via Marketplace + +Some custom apps are available through the **[Marketplace](./marketplace.md)**. Open Marketplace from Spotify's sidebar to browse. + +### Manual Installation + +1. Download or create the custom app folder (must contain at minimum `index.js` and `manifest.json`) + +2. Place it in your CustomApps folder: + + | Platform | Path | + |----------|------| + | **Windows** | `%appdata%\spicetify\CustomApps\` | + | **Linux / macOS** | `~/.config/spicetify/CustomApps/` | + +3. Enable the custom app: + + ```bash + spicetify config custom_apps + spicetify apply + ``` + +:::tip +The `config custom_apps` command **appends** to your existing custom apps. It doesn't replace them. +::: + +## Removing Custom Apps + +To remove a custom app, append a `-` after the folder name: + +```bash +spicetify config custom_apps - +spicetify apply +``` + +## Manual Config Editing + +You can also edit the config file directly. Custom apps are listed in the `custom_apps` key, separated by `|`: + +```ini +[AdditionalOptions] +custom_apps = reddit|lyrics-plus|new-releases +``` + +After editing, run `spicetify apply`. + +--- + +## Built-in Custom Apps + +These custom apps ship with Spicetify and are available immediately. + +### Lyrics Plus + +Advanced lyrics display with multiple providers (Musixmatch, Netease, LRCLIB). + +**Folder:** `lyrics-plus` + +```bash +spicetify config custom_apps lyrics-plus +spicetify apply +``` + +**Features:** +- Synced lyrics display +- Multiple lyrics sources +- Customizable colors and providers (via profile menu) + +![Lyrics Plus](/images/apps/lyrics-plus.png) + +:::note +If lyrics aren't loading, see the [FAQ](/docs/faq#sometimes-popup-lyrics-andor-lyrics-plus-seem-to-not-work) for Musixmatch token instructions. +::: + +Learn more: [Lyrics Plus on GitHub](https://github.com/spicetify/cli/tree/main/CustomApps/lyrics-plus) + +--- + +### New Releases + +Aggregates new releases from artists and podcasts you follow. + +**Folder:** `new-releases` + +```bash +spicetify config custom_apps new-releases +spicetify apply +``` + +**Features:** +- Filter by time range and release type +- Customizable date format (based on your locale) +- Settings in profile menu + +![New Releases](/images/apps/new-releases.png) + +--- + +### Reddit + +Browse Spotify-related subreddits and discover music shared by the community. + +**Folder:** `reddit` + +```bash +spicetify config custom_apps reddit +spicetify apply +``` + +**Features:** +- Fetch posts from music subreddits +- Add, remove, and arrange subreddits +- Customize post display (via profile menu) + +![Reddit](/images/apps/reddit.png) + +--- + +## Creating Custom Apps + +Want to build your own custom app? See the **[Custom Apps Development Guide](/docs/development/custom-apps)**. + +Custom apps are React applications. A basic app needs: + +- `index.js`: Main application code with a `render()` function +- `manifest.json`: Metadata including name, icons, and optional subfiles + +For a streamlined development experience, check out **[Spicetify Creator](/docs/development/spicetify-creator)** which supports TypeScript, JSX, and hot reloading. + +--- + +## Troubleshooting + +### Custom app not showing in sidebar + +1. Verify the folder is in the correct CustomApps location +2. Check that `manifest.json` exists and has valid JSON +3. Run `spicetify apply` +4. Restart Spotify + +### App shows but doesn't load + +1. Check the browser console for errors (Ctrl + Shift + I) +2. Verify `index.js` exports a `render()` function +3. Check for JavaScript syntax errors + +### Settings menu not appearing + +Custom app settings appear in the profile menu (top-right). Make sure the app implements settings correctly. Check the app's documentation. diff --git a/docs/customization/extensions.md b/docs/customization/extensions.md new file mode 100644 index 00000000..75910c62 --- /dev/null +++ b/docs/customization/extensions.md @@ -0,0 +1,245 @@ +--- +title: Extensions +description: Add features to Spotify with extensions. +--- + +Extensions are JavaScript files that add new features to Spotify. They run alongside Spotify's main code and can add buttons, modify behavior, and integrate with external services. + +## Installing Extensions + +### Via Marketplace + +The easiest way to install extensions is through the **[Marketplace](./marketplace.md)**. Open Marketplace from Spotify's sidebar and browse the Extensions tab. + +### Manual Installation + +For extensions not in Marketplace, or for Spicetify's built-in extensions: + +1. Place the extension file in your Extensions folder: + + | Platform | Path | + |----------|------| + | **Windows** | `%appdata%\spicetify\Extensions\` | + | **Linux / macOS** | `~/.config/spicetify/Extensions/` | + +2. Enable the extension: + + ```bash + spicetify config extensions + spicetify apply + ``` + +:::tip +The `config extensions` command **appends** to your existing extensions. It doesn't replace them. +::: + +## Removing Extensions + +To remove an extension, append a `-` after the filename: + +```bash +spicetify config extensions - +spicetify apply +``` + +## Manual Config Editing + +You can also edit the config file directly. Extensions are listed in the `extensions` key, separated by `|`: + +```ini +[AdditionalOptions] +extensions = fullAppDisplay.js|keyboardShortcut.js|trashbin.js +``` + +After editing, run `spicetify apply`. + +--- + +## Built-in Extensions + +These extensions ship with Spicetify and are available immediately after installation. + +### Full App Display + +A minimal, full-screen album art display with blur effect background. + +**Filename:** `fullAppDisplay.js` + +```bash +spicetify config extensions fullAppDisplay.js +spicetify apply +``` + +**Usage:** Click the button in the top bar to activate. Double-click anywhere to exit. Right-click to open settings. + +![Full App Display](/images/extensions/full-app-display.png) + +--- + +### Keyboard Shortcut + +Extends Spotify's keyboard shortcuts with vim-like navigation. + +**Filename:** `keyboardShortcut.js` + +```bash +spicetify config extensions keyboardShortcut.js +spicetify apply +``` + +**Shortcuts:** +- Ctrl + Tab / Ctrl + Shift + Tab: Navigate sidebar items +- Page Up / Page Down: Scroll the main page +- J / K: Scroll down/up (vim-style) +- G / Shift + G: Jump to top/bottom +- F: Open keyboard-driven navigation + +![Keyboard Shortcut](/images/extensions/keyboard-demo.png) + +--- + +### Bookmark + +Save and quickly access pages, tracks, or specific timestamps. + +**Filename:** `bookmark.js` + +```bash +spicetify config extensions bookmark.js +spicetify apply +``` + +**Usage:** Useful for bookmarking artists, albums, or playlists to check out later without following them. + +![Bookmark](/images/extensions/bookmark.png) + +--- + +### Trash Bin + +Skip songs or artists automatically. They'll never play again. + +**Filename:** `trashbin.js` + +```bash +spicetify config extensions trashbin.js +spicetify apply +``` + +**Usage:** Right-click any track or artist and select "Throw to Trashbin". Trashed items are automatically skipped. + +![Trash Bin](/images/extensions/trash.png) + +--- + +### Shuffle+ + +True shuffle using the Fisher-Yates algorithm (zero bias). + +**Filename:** `shuffle+.js` + +```bash +spicetify config extensions shuffle+.js +spicetify apply +``` + +**Usage:** Right-click any album, playlist, or artist and select "Play with Shuffle+". Also works with multi-selected tracks. + +![Shuffle+](/images/extensions/shuffle.png) + +--- + +### Loopy Loop + +Loop a specific portion of a track. + +**Filename:** `loopyLoop.js` + +```bash +spicetify config extensions loopyLoop.js +spicetify apply +``` + +**Usage:** Mark start and end points on the progress bar to loop that section automatically. + +![Loopy Loop](/images/extensions/loopy-loop.png) + +--- + +### Pop-up Lyrics + +Display lyrics in a separate pop-up window. + +**Filename:** `popupLyrics.js` + +```bash +spicetify config extensions popupLyrics.js +spicetify apply +``` + +**Usage:** Click the microphone icon in the top bar. Right-click for settings and lyrics provider options. + +![Pop-up Lyrics](/images/extensions/popup-lyrics.png) + +:::note +If lyrics aren't loading, see the [FAQ](/docs/faq#sometimes-popup-lyrics-andor-lyrics-plus-seem-to-not-work) for Musixmatch token instructions. +::: + +--- + +### Auto Skip Videos + +Automatically skip video content that can't play in your region. + +**Filename:** `autoSkipVideo.js` + +```bash +spicetify config extensions autoSkipVideo.js +spicetify apply +``` + +**Why:** Some video content is region-locked. Without this extension, playback just stops instead of moving to the next track. + +--- + +### Christian Spotify + +Automatically skip explicit tracks. + +**Filename:** `autoSkipExplicit.js` + +```bash +spicetify config extensions autoSkipExplicit.js +spicetify apply +``` + +**Usage:** Toggle in the profile menu (top-right button). + +![Christian Spotify](/images/extensions/christian-demo.png) + +--- + +### Web Now Playing + +Send track metadata to Rainmeter's WebNowPlaying plugin. + +**Filename:** `webnowplaying.js` + +```bash +spicetify config extensions webnowplaying.js +spicetify apply +``` + +**For minimal setup** (no UI changes): + +```bash +spicetify config inject_css 0 replace_colors 0 +spicetify config extensions webnowplaying.js +spicetify apply +``` + +--- + +## Creating Extensions + +Want to build your own extension? See the **[Development Guide](/docs/development)** and **[Spicetify Creator](/docs/development/spicetify-creator)** for tools and tutorials. diff --git a/docs/customization/index.md b/docs/customization/index.md new file mode 100644 index 00000000..270751cb --- /dev/null +++ b/docs/customization/index.md @@ -0,0 +1,48 @@ +--- +title: Customization +description: Customize Spotify with themes, extensions, and custom apps. +--- + +Spicetify lets you customize Spotify in three ways: + +| Type | What it does | +|------|--------------| +| **[Themes](./themes.md)** | Change colors, fonts, and visual styling | +| **[Extensions](./extensions.md)** | Add new features and functionality | +| **[Custom Apps](./custom-apps.md)** | Add entirely new pages to the sidebar | + +## Marketplace vs Manual Installation + +There are two ways to install customizations: + +### Marketplace (Recommended) + +The **[Spicetify Marketplace](./marketplace.md)** is a built-in browser that lets you discover, install, and manage themes, extensions, and snippets directly from Spotify's sidebar. + +If you followed the [Getting Started](/docs/getting-started) guide, you already have Marketplace installed. + +**Use Marketplace when:** +- You want a simple, visual way to browse and install customizations +- You prefer one-click installation +- You want automatic updates + +### Manual Installation + +Manual installation gives you direct control over your Spicetify configuration. + +**Use manual installation when:** +- The theme/extension isn't available in Marketplace +- You're developing your own customizations +- You want to use built-in extensions that ship with Spicetify +- You need precise control over what's installed + +Each customization page in this section covers both Marketplace usage and manual installation. + +## Configuration + +All manual customizations are controlled through: + +- **CLI commands**: `spicetify config ` followed by `spicetify apply` +- **Config file**: Direct editing of `config-xpui.ini` + +See the **[Configuration Reference](./config-file.md)** for details on the config file and all available options. diff --git a/docs/customization/marketplace.md b/docs/customization/marketplace.md new file mode 100644 index 00000000..f8116d19 --- /dev/null +++ b/docs/customization/marketplace.md @@ -0,0 +1,121 @@ +--- +title: Marketplace +description: Browse and install themes, extensions, and snippets from Spotify. +--- + +The Spicetify Marketplace is a built-in store that lets you browse, install, and manage customizations directly from Spotify. + +## Installation + +If you followed the [Getting Started](/docs/getting-started) guide, Marketplace is already installed. If not: + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```powershell +iwr -useb https://raw.githubusercontent.com/spicetify/marketplace/main/resources/install.ps1 | iex +``` + + + + +```bash +curl -fsSL https://raw.githubusercontent.com/spicetify/marketplace/main/resources/install.sh | sh +``` + + + + +## Using Marketplace + +After installation, you'll see a **Marketplace** item in Spotify's sidebar. Click it to open the store. + +### Browsing + +The Marketplace has several tabs: + +- **Extensions**: Add features like lyrics display, keyboard shortcuts, and more +- **Themes**: Change Spotify's visual appearance +- **Snippets**: Small CSS tweaks for minor visual adjustments + +Use the search bar to find specific items, or browse by category. + +### Installing + +1. Click on any item to see its details +2. Click **Install** to add it to your Spotify +3. The change takes effect immediately (no restart needed for most items) + +### Managing Installed Items + +Click the **Installed** tab to see everything you've added. From here you can: + +- **Enable/Disable**: Toggle items on and off without uninstalling +- **Uninstall**: Remove items completely +- **Update**: Apply updates when available (indicated by a badge) + +## Marketplace vs Manual + +| Feature | Marketplace | Manual | +|---------|-------------|--------| +| One-click install | Yes | No | +| Automatic updates | Yes | No | +| Built-in extensions | Some | All | +| Custom/local files | No | Yes | +| Fine-grained control | Limited | Full | + +For built-in extensions that ship with Spicetify (like Full App Display, Keyboard Shortcuts, etc.), see the **[Extensions](./extensions.md)** page for manual installation instructions. + +## Troubleshooting + +### Marketplace not showing in sidebar + +1. Make sure you ran the Marketplace install script +2. Run `spicetify apply` to ensure changes are applied +3. Restart Spotify + +### Items not installing + +1. Check your internet connection +2. Try running `spicetify restore backup apply` to refresh the installation +3. Check the [GitHub Issues](https://github.com/spicetify/marketplace/issues) for known problems + +### Marketplace disappeared after Spotify update + +After Spotify updates, you may need to re-apply Spicetify: + +```bash +spicetify backup apply +``` + +### Resetting Marketplace + +If Marketplace becomes unresponsive or you cannot access its settings: + +1. Enable DevTools: + + ```bash + spicetify enable-devtools + ``` + +2. Open DevTools in Spotify (Ctrl + Shift + I or Cmd + Option + I) + +3. In the Console tab, run: + + ```js + Marketplace.reset() + ``` + + This resets all Marketplace localStorage data. You can also reset specific types: + + ```js + Marketplace.reset("theme") // Reset theme only + Marketplace.reset("extensions") // Reset extensions only + Marketplace.reset("snippets") // Reset snippets only + Marketplace.reset("theme", "snippets") // Reset multiple types + ``` + +4. Restart Spotify diff --git a/docs/customization/themes.md b/docs/customization/themes.md new file mode 100644 index 00000000..92087010 --- /dev/null +++ b/docs/customization/themes.md @@ -0,0 +1,146 @@ +--- +title: Themes +description: Change Spotify's visual appearance with themes. +--- + +Themes let you customize Spotify's colors, fonts, and visual styling. From subtle tweaks to complete visual overhauls, themes are one of the most popular Spicetify features. + +## Installing Themes + +### Via Marketplace + +The easiest way to install themes is through the **[Marketplace](./marketplace.md)**. Open Marketplace from Spotify's sidebar and browse the Themes tab. + +### Manual Installation + +For themes not in Marketplace: + +1. Download the theme folder (should contain `color.ini` and `user.css`) + +2. Place it in your Themes folder: + + | Platform | Path | + |----------|------| + | **Windows** | `%appdata%\spicetify\Themes\` | + | **Linux / macOS** | `~/.config/spicetify/Themes/` | + +3. Apply the theme: + + ```bash + spicetify config current_theme + spicetify apply + ``` + +### Color Schemes + +Many themes include multiple color schemes. To use a specific scheme: + +```bash +spicetify config current_theme color_scheme +spicetify apply +``` + +Check the theme's `color.ini` file to see available schemes (each `[SectionName]` is a scheme). + +## Removing Themes + +To go back to Spotify's default appearance, set the theme to an empty value: + +```bash +spicetify config current_theme "" +spicetify apply +``` + +Or set a different theme name. + +--- + +## Community Themes + +The Spicetify community has created many themes. Here are some popular repositories: + +### Official Repository + +The official collection, open for contributions: + +- **[spicetify/spicetify-themes](https://github.com/spicetify/spicetify-themes)** + +### Popular Third-Party Themes + +| Theme | Description | +|-------|-------------| +| [Comfy](https://github.com/NYRI4/Comfy-spicetify) | Comfortable, modern design | +| [Fluent](https://github.com/williamckha/spicetify-fluent) | Windows 11 Fluent Design style | +| [Catppuccin](https://github.com/catppuccin/spicetify) | Soothing pastel color palette | +| [Bloom](https://github.com/nimsandu/spicetify-bloom) | Gradient-heavy, vibrant look | +| [Lucid](https://github.com/sanoojes/spicetify-lucid) | Clean, minimal aesthetic | +| [Gruvify](https://github.com/Skaytacium/Gruvify) | Gruvbox color scheme | +| [Spotify Dark](https://github.com/SyndiShanX/Spotify-Dark) | Enhanced dark theme | +| [Throwback](https://github.com/bluedrift/Spicetify-Throwback) | Classic Spotify look | +| [SpicetifyCat](https://github.com/Adrien5902/SpicetifyCat) | Cat-themed customization | +| [RetroPlayer](https://github.com/Seglats/Spicetify-retro) | Retro aesthetic | +| [Dracula (m0squdev)](https://github.com/m0squdev/dracula-spicetify-theme) | Dracula color palette | + +### Unmaintained (May Not Work) + +These themes may not work with current Spotify versions: + +- [Nord-Spotify](https://github.com/Tetrax-10/Nord-Spotify) +- [Dribbblish Dynamic](https://github.com/JulienMaille/dribbblish-dynamic-theme) +- [Dracula (official)](https://github.com/dracula/spicetify) + +--- + +## Creating Themes + +Want to create your own theme? See the **[Theme Development Guide](/docs/development/themes)**. + +A basic theme needs two files: + +- `color.ini`: Color values that become CSS variables +- `user.css`: Custom CSS rules + +Example `color.ini`: + +```ini +[Base] +main = 121212 +sidebar = 000000 +player = 181818 +card = 282828 +shadow = 000000 +selected-row = 797979 +button = 1db954 +button-active = 1ed760 +text = ffffff +subtext = b3b3b3 +``` + +--- + +## Troubleshooting + +### Theme not applying + +1. Make sure the theme folder name matches what you used in `spicetify config` +2. Verify the folder contains both `color.ini` and `user.css` +3. Run `spicetify apply` after any config changes + +### Theme looks broken after Spotify update + +After Spotify updates, themes may need adjustment. Try: + +```bash +spicetify restore backup apply +``` + +If issues persist, check the theme's repository for updates or reported issues. + +### Colors not changing + +Make sure you're setting both the theme and color scheme: + +```bash +spicetify config current_theme MyTheme color_scheme Dark +spicetify apply +``` diff --git a/docs/development/custom-apps.md b/docs/development/custom-apps.md index 01925b65..f7980483 100644 --- a/docs/development/custom-apps.md +++ b/docs/development/custom-apps.md @@ -3,9 +3,23 @@ title: Custom Apps description: πŸ”§ Creating Custom Apps. --- -## How to start +## App Structure + +```text +~/.config/spicetify/CustomApps/ # Linux/macOS +%appdata%\spicetify\CustomApps\ # Windows +└── my-app/ + β”œβ”€β”€ index.js # Required: main entry with render() + β”œβ”€β”€ manifest.json # Required: app metadata and icons + β”œβ”€β”€ style.css # Optional: custom styles + └── src/ # Optional: additional JS files + β”œβ”€β”€ Component.js + └── ... +``` + +## How to Start -- Make a new folder for your custom app in your [CustomApps folder](/docs/advanced-usage/custom-apps). You'll install it like any other custom app. +- Make a new folder for your custom app in your [CustomApps folder](/docs/customization/custom-apps). You'll install it like any other custom app. - Create an `index.js` and a `manifest.json` inside that folder. - The `index.js` file is the main file for the custom app. - The manifest includes some important information to make the custom app work. diff --git a/docs/development/extensions.md b/docs/development/extensions.md new file mode 100644 index 00000000..13273073 --- /dev/null +++ b/docs/development/extensions.md @@ -0,0 +1,288 @@ +--- +title: Extensions +description: Creating extensions for Spicetify. +--- + +Extensions are JavaScript files that run alongside Spotify's main code. They can add UI elements, modify behavior, integrate with external services, and more. + +## Extension Structure + +```text +~/.config/spicetify/Extensions/ # Linux/macOS +%appdata%\spicetify\Extensions\ # Windows +β”œβ”€β”€ myExtension.js +β”œβ”€β”€ anotherExtension.js +└── ... +``` + +Extensions are single JavaScript files. For complex extensions with multiple files, use [Spicetify Creator](/docs/development/spicetify-creator). + +## Getting Started + +### Location + +Place your extension file in the Extensions folder: + +| Platform | Path | +|----------|------| +| **Windows** | `%appdata%\spicetify\Extensions\` | +| **Linux / macOS** | `~/.config/spicetify/Extensions/` | + +### Minimal Extension + +```js +// myExtension.js +(function myExtension() { + // Wait for Spicetify to be ready + if (!Spicetify.Player || !Spicetify.Platform) { + setTimeout(myExtension, 100); + return; + } + + console.log("My extension loaded!"); + + // Your code here +})(); +``` + +### Testing Your Extension + +1. Save your file to the Extensions folder +2. Enable it: + + ```bash + spicetify config extensions myExtension.js + spicetify apply + ``` + +3. Open DevTools in Spotify to see console output: + - **Windows/Linux**: Ctrl + Shift + I + - **macOS**: Cmd + Option + I + + +--- + +## The Spicetify API + +Extensions access Spotify through the global `Spicetify` object. Key namespaces: + +| Namespace | Purpose | +|-----------|---------| +| `Spicetify.Player` | Playback control (play, pause, skip, volume) | +| `Spicetify.Platform` | Core platform APIs (history, library, playlists) | +| `Spicetify.CosmosAsync` | HTTP requests to Spotify's internal API | +| `Spicetify.URI` | Parse and create Spotify URIs | +| `Spicetify.React` | React instance for UI components | +| `Spicetify.ReactDOM` | ReactDOM for rendering | +| `Spicetify.Topbar` | Add buttons to the top bar | +| `Spicetify.Playbar` | Add buttons to the player bar | +| `Spicetify.ContextMenu` | Add items to right-click menus | + +See the **[API Wrapper Reference](/docs/development/api-wrapper)** for complete documentation. + +--- + +## Common Patterns + +### Waiting for Spicetify + +Always wait for Spicetify to be ready before accessing its APIs: + +```js +(function init() { + if (!Spicetify.Player || !Spicetify.Platform) { + setTimeout(init, 100); + return; + } + + main(); +})(); + +function main() { + // Safe to use Spicetify here +} +``` + +### Adding a Top Bar Button + +```js +const button = new Spicetify.Topbar.Button( + "My Button", + `...`, // SVG icon + () => { + console.log("Button clicked!"); + } +); +``` + +### Adding a Context Menu Item + +```js +new Spicetify.ContextMenu.Item( + "My Menu Item", + (uris) => { + console.log("Selected URIs:", uris); + }, + (uris) => { + // Return true to show this item + return true; + }, + `...` // Optional icon +).register(); +``` + +### Listening to Player Events + +```js +Spicetify.Player.addEventListener("songchange", (event) => { + const track = Spicetify.Player.data?.item; + console.log("Now playing:", track?.name); +}); +``` + +### Making API Requests + +```js +// GET request +const response = await Spicetify.CosmosAsync.get( + "https://api.spotify.com/v1/me/player" +); + +// POST request +await Spicetify.CosmosAsync.post( + "https://api.spotify.com/v1/me/player/play", + { uris: ["spotify:track:..."] } +); +``` + +### Storing Data + +```js +// Save +Spicetify.LocalStorage.set("myExtension:setting", "value"); + +// Load +const value = Spicetify.LocalStorage.get("myExtension:setting"); +``` + +### Showing Notifications + +```js +Spicetify.showNotification("Hello from my extension!"); +``` + +--- + +## UI Development + +### Using React + +Spicetify exposes React for building UI: + +```js +const { React, ReactDOM } = Spicetify; +const { useState, useEffect } = React; + +function MyComponent() { + const [count, setCount] = useState(0); + + return React.createElement("button", { + onClick: () => setCount(c => c + 1) + }, `Clicked ${count} times`); +} +``` + +### Using Spotify's Components + +Access Spotify's internal React components: + +```js +const { Button, Toggle } = Spicetify.ReactComponent; + +// Use in your components +React.createElement(Button, { + onClick: () => console.log("clicked") +}, "Click me"); +``` + +### Creating Modals + +```js +Spicetify.PopupModal.display({ + title: "My Modal", + content: React.createElement("div", null, "Hello!"), +}); +``` + +--- + +## Spicetify Creator + +For a better development experience with TypeScript, JSX, and hot reloading, use **[Spicetify Creator](/docs/development/spicetify-creator)**. + +```bash +npx spicetify-creator +``` + +Benefits: +- TypeScript support with full type definitions +- JSX syntax (no manual `React.createElement`) +- Hot reloading during development +- Build tooling (bundling, minification) + +--- + +## Best Practices + +### Performance + +- Avoid polling. Use event listeners when possible +- Debounce expensive operations +- Clean up listeners when no longer needed + +### Error Handling + +```js +try { + const data = await Spicetify.CosmosAsync.get("..."); +} catch (error) { + console.error("Request failed:", error); + Spicetify.showNotification("Something went wrong", true); +} +``` + +### Compatibility + +- Test with both light and dark themes +- Check for API existence before using (APIs can change between Spotify versions) +- Use feature detection: + +```js +if (Spicetify.Topbar?.Button) { + // Safe to use +} +``` + +### Naming + +- Use a unique prefix for localStorage keys: `myExtension:key` +- Use descriptive function and variable names + +--- + +## Publishing + +To share your extension: + +1. **GitHub**: Create a repository with your extension file(s) and installation instructions + +2. **Marketplace**: Submit to the [Spicetify Marketplace](https://github.com/spicetify/marketplace) for easy discovery and installation + +--- + +## Resources + +- **[API Wrapper Reference](/docs/development/api-wrapper)**: Complete API documentation +- **[Spicetify Creator](/docs/development/spicetify-creator)**: TypeScript development tool +- **[Built-in Extensions](https://github.com/spicetify/cli/tree/main/Extensions)**: Reference implementations +- **[Marketplace Extensions](https://github.com/spicetify/marketplace)**: Community examples diff --git a/docs/development/themes.md b/docs/development/themes.md index 7b6252ea..049d98b0 100644 --- a/docs/development/themes.md +++ b/docs/development/themes.md @@ -3,6 +3,21 @@ title: Themes description: ✨ Creating Themes for Spicetify. --- +## Theme Structure + +```text +~/.config/spicetify/Themes/ # Linux/macOS +%appdata%\spicetify\Themes\ # Windows +└── MyTheme/ + β”œβ”€β”€ color.ini # Required: color definitions + β”œβ”€β”€ user.css # Required: custom CSS rules + β”œβ”€β”€ theme.js # Optional: theme-specific JavaScript + └── assets/ # Optional: images, fonts, etc. + └── ... +``` + +## Theme Location + There are 2 places you can put your themes: 1. `Themes` folder in Home directory diff --git a/docs/getting-started.md b/docs/getting-started.md index f5fcd276..17c4128c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -5,43 +5,294 @@ sidebar_position: 1 Spicetify is a multiplatform command-line tool to customize the official Spotify client. +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## Installation ### Windows -This is the installation method we recommend for most users. It is the fastest and most reliable way to install Spicetify. - -#### Powershell (pre-built binary) + + ```powershell iwr -useb https://raw.githubusercontent.com/spicetify/cli/main/install.ps1 | iex ``` -Also run the following if you would like to install the [**Spicetify Marketplace**](https://github.com/spicetify/marketplace), which gives you access to a tab in Spotify's sidebar that allows you to search for and install _themes_, _extensions_, and _snippets_. + + + ```powershell -iwr -useb https://raw.githubusercontent.com/spicetify/marketplace/main/resources/install.ps1 | iex +winget install Spicetify.Spicetify +``` + + + + +```powershell +scoop install spicetify-cli ``` -### Linux and MacOS + + + +```powershell +choco install spicetify-cli +``` + +See the [Chocolatey package page](https://chocolatey.org/packages/spicetify-cli) for more details. + + + + +
+Spotify from Scoop + +If you installed Spotify via Scoop, find its location and set it in your config: + +```console +$ scoop prefix spotify +C:\Users\\scoop\apps\spotify\current +``` + +```powershell +spicetify config spotify_path "C:\Users\\scoop\apps\spotify\current" +``` + +
+ +### Linux + + + + +```bash +curl -fsSL https://raw.githubusercontent.com/spicetify/cli/main/install.sh | sh +``` + + + + +```bash +brew install spicetify-cli +``` + + + + +```bash +yay -S spicetify-cli +``` + + + + +#### Linux-Specific Setup + +Depending on how you installed Spotify, you may need additional configuration. + +
+Spotify from AUR + +Grant write permissions to Spotify's directory: + +```bash +sudo chmod a+wr /opt/spotify +sudo chmod a+wr /opt/spotify/Apps -R +``` + +
+ +
+Spotify from spotify-launcher (Arch) + +The `spotify-launcher` package installs Spotify to a user directory. Set the path in your config: + +```bash +spicetify config spotify_path "$HOME/.local/share/spotify-launcher/install/usr/share/spotify" +``` + +:::warning +When setting config values, use the full absolute path (e.g., `/home/username/...`). The `~` shortcut works in shell commands but not in config values. +::: + +
+ +
+Spotify from Snap + +Snap apps cannot be modified. You'll need to switch to the apt version: + +1. Remove Snap Spotify: + + ```bash + snap remove spotify + ``` + +2. Install via apt: + + ```bash + curl -sS https://download.spotify.com/debian/pubkey_C85668DF69375001.gpg | sudo gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/spotify.gpg + echo "deb http://repository.spotify.com stable non-free" | sudo tee /etc/apt/sources.list.d/spotify.list + sudo apt-get update && sudo apt-get install spotify-client + ``` + +3. Grant permissions: + + ```bash + sudo chmod a+wr /usr/share/spotify + sudo chmod a+wr /usr/share/spotify/Apps -R + ``` + +
+ +
+Spotify from Flatpak + +1. Find your Flatpak Spotify location: -#### Shell (pre-built binary) -Spicetify CLI -```sh + ```bash + flatpak --installations + ``` + + Common locations: + - `/var/lib/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify/` + - `~/.local/share/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify/` + +2. Set the path: + + ```bash + spicetify config spotify_path "/var/lib/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify" + ``` + +3. Find and set your prefs file (check both locations): + + ```bash + # Check which exists: + ls ~/.config/spotify/prefs + ls ~/.var/app/com.spotify.Client/config/spotify/prefs + + # Set whichever exists (use the full absolute path): + spicetify config prefs_path /home/username/.var/app/com.spotify.Client/config/spotify/prefs + ``` + +4. Grant permissions: + + ```bash + sudo chmod a+wr /var/lib/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify + sudo chmod a+wr -R /var/lib/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify/Apps + ``` + +
+ +### macOS + + + + +```bash curl -fsSL https://raw.githubusercontent.com/spicetify/cli/main/install.sh | sh ``` -Spicetify Marketplace -```sh + + + + +```bash +brew install spicetify-cli +``` + +After installing via Homebrew, set the Spotify path: + +```bash +spicetify config spotify_path "/Applications/Spotify.app/Contents/Resources" +``` + + + + +--- + +## Before First Run + +:::tip +If this is a fresh Spotify install, open Spotify and log in for at least 60 seconds before running Spicetify. This allows Spotify to generate the files that Spicetify needs to function. +::: + +--- + +## Marketplace + +The [Spicetify Marketplace](https://github.com/spicetify/marketplace) gives you a tab in Spotify's sidebar to browse and install themes, extensions, and snippets. + + + + +```powershell +iwr -useb https://raw.githubusercontent.com/spicetify/marketplace/main/resources/install.ps1 | iex +``` + + + + +```bash curl -fsSL https://raw.githubusercontent.com/spicetify/marketplace/main/resources/install.sh | sh ``` -
+ + + +--- ## Basic Usage -After installing Spicetify and Spicetify's Marketplace, you can use it to customize your Spotify client using all the available **extensions** and **themes** found in the Marketplace. +After installing Spicetify and Marketplace, you can customize Spotify using themes and extensions from the Marketplace tab in Spotify's sidebar. ### Updating -**_Spotify_**, every now and then, **updates** its client. Since we have no power over this process, you will likely need to **re-apply Spicetify**. +Spotify updates periodically. After a Spotify update, you'll need to re-apply Spicetify: + +```bash +spicetify backup apply +``` + +If that doesn't work, Spicetify itself may need an update: + +```bash +spicetify update +``` + +If you updated Spicetify via a package manager (Homebrew, AUR, etc.) or the update command didn't fully apply changes, run: + +```bash +spicetify restore backup apply +``` + +If no Spicetify upgrade is available yet, the team is likely still working on compatibility with the new Spotify version. + +--- + +## Legacy Versions + +If you need an older Spicetify version (e.g., for Spotify v1.1.56 or older): + + + + +```powershell +$v="1.2.1"; Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/spicetify/cli/main/install.ps1" | Invoke-Expression +``` + + + + +```bash +curl -fsSL https://raw.githubusercontent.com/spicetify/cli/main/install.sh -o /tmp/install.sh +sh /tmp/install.sh 1.2.1 +``` + + + -However, the update might have major changes to the client, which means you will need to run `spicetify update` (`spicetify upgrade` in Spicetify versions **below 2.27.0**) every time you update Spotify. If no update for Spicetify is available, it means that it either still works by simply running `spicetify backup apply`, or that we are still **working on updating Spicetify** to work on the new version. +Legacy resources: +- [Spicetify v1 source (legacy branch)](https://github.com/spicetify/cli/tree/legacy) +- [Legacy themes](https://github.com/spicetify/spicetify-themes/tree/legacy) diff --git a/docs/uninstallation.md b/docs/uninstallation.md new file mode 100644 index 00000000..c9854fbe --- /dev/null +++ b/docs/uninstallation.md @@ -0,0 +1,111 @@ +--- +title: Uninstallation +description: How to remove Spicetify from your system. +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Quick Uninstall + + + + +```powershell +spicetify restore +rmdir -r -fo $env:APPDATA\spicetify +rmdir -r -fo $env:LOCALAPPDATA\spicetify +``` + + + + +```bash +spicetify restore +rm -rf ~/.spicetify +rm -rf ~/.config/spicetify +``` + + + + +## Step by Step + +### 1. Restore Spotify + +First, remove Spicetify modifications from Spotify: + +```bash +spicetify restore +``` + +This returns Spotify to its vanilla state. + +### 2. Remove Spicetify Files + + + + +Remove the config and data directories: + +```powershell +rmdir -r -fo $env:APPDATA\spicetify +rmdir -r -fo $env:LOCALAPPDATA\spicetify +``` + + + + +Remove the config and data directories: + +```bash +rm -rf ~/.spicetify +rm -rf ~/.config/spicetify +``` + + + + +### 3. Remove the Binary (Optional) + +If you installed via a package manager, use it to uninstall: + +| Method | Uninstall Command | +|--------|-------------------| +| Scoop | `scoop uninstall spicetify-cli` | +| Winget | `winget uninstall Spicetify.Spicetify` | +| Chocolatey | `choco uninstall spicetify-cli` | +| Homebrew | `brew uninstall spicetify-cli` | +| AUR | `yay -R spicetify-cli` | + +If you used the install script, the binary is in your PATH. You can find and remove it: + + + + +```powershell +where spicetify +# Remove the file shown +``` + + + + +```bash +which spicetify +# Remove the file shown, e.g.: +rm $(which spicetify) +``` + + + + +## Keeping Configuration + +If you might reinstall later and want to keep your settings: + +```bash +spicetify restore +``` + +This removes Spicetify from Spotify but preserves your config file, themes, and extensions. diff --git a/docusaurus.config.js b/docusaurus.config.js index e64c2504..f74fe467 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -105,8 +105,8 @@ const config = { to: '/docs/getting-started', }, { - label: 'Advanced Usage', - to: '/docs/advanced-usage', + label: 'Customization', + to: '/docs/customization', }, { label: 'Development', diff --git a/sidebars.js b/sidebars.js index 6b62cbb5..1416236b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -13,40 +13,46 @@ /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { - // By default, Docusaurus generates a sidebar from the docs folder structure sidebar: [ 'getting-started', { type: 'category', - label: 'Advanced Usage', + label: 'Customization', collapsed: false, link: { - type: 'generated-index', - description: - 'A guide about advanced usage of Spicetify and venturing outside of the Spicetify Marketplace.', - slug: '/advanced-usage', + type: 'doc', + id: 'customization/index', }, items: [ - 'advanced-usage/installation', - 'advanced-usage/uninstallation', - 'advanced-usage/command-line-interface', - 'advanced-usage/themes', - 'advanced-usage/extensions', - 'advanced-usage/custom-apps', + 'customization/marketplace', + 'customization/themes', + 'customization/extensions', + 'customization/custom-apps', + 'customization/config-file', ], }, + { + type: 'category', + label: 'CLI Reference', + link: { + type: 'doc', + id: 'cli/index', + }, + items: ['cli/commands'], + }, { type: 'category', label: 'Development', link: { type: 'generated-index', description: - "Let's learn about how to contribute to the Spicetify community!", + 'Learn how to create themes, extensions, and custom apps for Spicetify.', slug: '/development', }, items: [ 'development/compiling', 'development/themes', + 'development/extensions', 'development/custom-apps', 'development/js-modules', 'development/react-devtools', @@ -275,6 +281,7 @@ const sidebars = { ], }, 'faq', + 'uninstallation', ], };