Getting Started

Recommended / Required Development Utilities

• NodeJS 14.0.0 or greater

• pnpm (Optional, but highly recommended)

• Git

• Python 3.8 or greater

• Basic Command Line Knowledge

::alert{type="warning"} While not required, PNPM is recommended for compiling Cider, and you can install it by using:

npm install -g pnpm ::

Cloning the repository

Open a terminal window in the directory you'd like Git to clone to and enter the following command

git clone https://github.com/ciderapp/Cider.git

Optionally, if you'd like to use the Development branch of Cider to test upcoming features switch your branch by moving your terminal into the directory and using git to checkout the branch by entering the following commands

cd Cider\
git checkout develop

::alert{type="note" title="Success"} If you'd like to update your repository in the future to keep up to date, use the command (Make sure you're in the directory, you originally cloned in)

git pull

Installing Dependencies

Now for the fun part, by using pnpm, npm or yarn (we'll be using pnpm in this case) enter the following command to automatically obtain all required dependencies for installation.

pnpm install

npm install --force

yarn install

::alert{type="note"} This step could take a little while on some machines. ::

Compiling Cider

This step takes a little while on the first compilation so bear with it as it does what it needs to do.

Compiling Cider for specific CPU architectures is a smart thing to do and you can do it by adding switches to the dist argument as displayed.

// For x86_64 machines. (Modern PC's)
pnpm dist -l --x64

// For x86 ONLY machines. (Legacy PC's)
pnpm dist -l --ia32

// For x86_64 machines. (Modern PC's)
npm run dist -l --x64

// For x86 ONLY machines. (Legacy PC's)
npm run dist -l --ia32

// For x86_64 machines. (Modern PC's)
yarn dist -l --x64

// For x86 ONLY machines. (Legacy PC's)
yarn dist -l --ia32

::alert{type="warning"} On some low-end machines this process could take up to ~10 minutes. ::

::alert{type="warning"} This command would build three separate packages of Cider, AppImage, .deb, and .snap packages ::

Compiling Cider from AUR

If you are on an arch-based Linux distribution and have an AUR helper (pacman/yay/paru/etc.), then you are in luck. Cider has 2 PKGBUILD's in the Arch User Repository.

Assuming you already have access to the AUR and have a friendly AUR helper (we will use yay for this example) enter the following command to automatically obtain all required dependencies for installation.

::alert{type="tip"} If you like to live on the bleeding edge, use the cider-git package, this will compile directly from the main branch. :;

yay -S cider

::alert{type="warning"} Running this on Node.js 17 or later will fail. This is due to Node.js 17 no longer writing openssl_fips to config.gypi so it's not there in Node.js 17's process.config. It is suggested to downgrade to nodejs-lts-gallium to resolve this issue. ::

Installing Cider

Your new Cider installation setup file is ready for you! You can find your setup executable in your cloned folder directory on your system in the subfolder dist/ and from there you'll see your new Setup files. Choose the installer that best matches your distro.

::alert{type="note" title="Success"} Congrats! You've successfully compiled your own build of Cider! ::

Getting Started

Recommended / Required Development Utilities

• NodeJS 14.0.0 or greater

• pnpm (Optional, but highly recommended)

• Git

• Python 3.8 or greater

• Xcode 11+

• Have an Apple Developer Account and be a member of the Apple Developer Program. This is necessary to play music through the app.

• Basic Command Line Knowledge

::alert{type="warning"} While not required, PNPM is recommended for compiling Cider, and you can install it by using:

npm install -g pnpm ::

::alert{type="caution"} To remind you again, if you don't have an Apple Developer account to sign the Cider binary after building, it WILL NOT work. ::

Cloning the repository

Open a command prompt window in the directory you'd like Git to clone to and enter the following command

git clone https://github.com/ciderapp/Cider.git

Optionally, if you'd like to use the Development branch of Cider to test upcoming features switch your branch by moving your terminal into the directory and using git to checkout the branch by entering the following commands

cd Cider/
git checkout develop

::alert{type="tip"} If you'd like to update your repository in the future to keep up to date, use the command (Make sure you're in the directory, you originally cloned in)

git pull ::

Installing Dependencies

Now for the fun part, by using pnpm, npm or yarn (we'll be using pnpm in this case) enter the following command to automatically obtain all required dependencies for installation.

pnpm install

npm install --force

yarn install

::alert{type="note"} This step could take a little while on some machines. ::

Create an account to VMP-sign Cider.

What is this for? MacOS doesn't like development Widevine DRM keys for some reason. Therefore, we need to sign our own production keys here. This can be done as follows:

python3 -m pip install --upgrade castlabs-evs
python3 -m castlabs_evs.account signup
Signing up for castLabs EVS
 - A valid e-mail address is required for account verification
>> E-mail Address []: me@example.com
>> First Name []: Me
>> Last Name []: Example
>> Organization []: Example, Inc
>> Account Name []: example
>> Password []: XXXXXXXX
>> Verify Password []: XXXXXXXX
Confirming EVS account
 - A confirmation code has been sent to your e-mail address
>> Confirmation Code []: XXXXXX
Discarding authorization token(s)
Refreshing authorization token(s)

Remember your account name and password because you will need it later.

Once in a while, you may need to re-authenticate the VMP account. If that is the case:

python3 -m castlabs_evs.account reauth
Discarding authorization token(s)
Refreshing authorization token(s)
>> Account Name [example]: 
>> Password []: XXXXXXXX

Create Apple signing keys and app-specific password.

1. In Xcode: Under Xcode > Preferences (⌘,) > Accounts, you may add your Apple ID. With your team selected, the View Details... in the bottom right could find you the available certificates for generation/download.

2. After that, select all of the certificates in Keychain Access to generate as a .p12 file. Remember the file location and the .p12 password.

3. Generate the app-specific password of your Apple Developer account

Setting up environment variables.

export CSC_LINK= <location to the p12 certificate>
export CSC_KEY_PASSWORD= <p12 certificate password>
export APPLEID= <your Apple Developer email address>
export APPLEIDPASS= <your Apple Developer app-specific password>

You can set the environment variables permanently by edit the ~/.bash-profile file and add the above lines at the bottom of the file.

~/.bash-profile

Final fixes

Electron-Packager doesn't like MacOS notarization. You need to manually patch the files in order for it to work properly:

cp resources/verror-types node_modules/@types/verror/index.d.ts
cp resources/macPackager.js node_modules/app-builder-lib/out/macPackager.js 

Compiling Cider

This step takes a little while on the first compilation so bear with it as it does what it needs to do.

This will generate a universal signed and notarized binary. (Don't mind the "not working" command line, it works)

pnpm dist:universalNotWorking -p never

npm run dist:universalNotWorking -p never

yarn dist:universalNotWorking -p never

::alert{type="warning"} On some low-end machines this process could take up to ~20-30 minutes. (It will look like it hangs at the notarization part, don't exit it). ::

Installing Cider

Your new Cider installation setup file is ready for you! You can find your setup executable in your cloned folder directory on your system in the subfolder dist/ and from there you'll see your new Setup file.

::alert{type="note" title="Success"} Congrats! You've successfully compiled your own build of Cider! ::

Getting Started

Recommended / Required Development Utilities

• NodeJS 14.0.0 or greater

• pnpm (Optional, but highly recommended)

• Git

• Python 3.8 or greater

• Basic Command Line Knowledge

• windows-build-tools

::alert{type="warning"} While not required, PNPM is recommended for compiling Cider, and you can install it by using:

npm install -g pnpm ::

::alert{type="caution"} You need windows-build-tools to be able to compile the native modules Cider uses for Windows. It should be installed with Node.js through the chocolatey package manager. If the installation fails you can install it using pnpm/npm in an administrator powershell/cmd window and entering:

pnpm install -g windows-build-tools

or

npm install -g windows-build-tools ::

Cloning the repository

Open a command prompt window in the directory you'd like Git to clone to and enter the following command

git clone https://github.com/ciderapp/Cider.git

Optionally, if you'd like to use the Development branch of Cider to test upcoming features switch your branch by moving your terminal into the directory and using git to checkout the branch by entering the following commands

cd Cider/
git checkout develop

::alert{type="tip"} If you'd like to update your repository in the future to keep up to date, use the command (Make sure you're in the directory, you originally cloned in)

git pull ::

Installing Dependencies

Now for the fun part, by using pnpm, npm or yarn (we'll be using pnpm in this case) enter the following command to automatically obtain all required dependencies for installation.

pnpm install

npm install --force

yarn install

::alert{type="tip"} This step could take a little while on some machines. ::

Compiling Cider

This step takes a little while on the first compilation so bare with it as it does what it needs to do.

Compiling Cider for specific CPU architectures is a smart thing to do and you can do it by adding switches to the dist argument as displayed.

// For x86_64 machines. (Modern PC's)
pnpm dist -w --x64

// For x86 ONLY machines. (Legacy PC's)
pnpm dist -w --ia32

// For x86_64 machines. (Modern PC's)
npm run dist -w --x64

// For x86 ONLY machines. (Legacy PC's)
npm run dist -w --ia32

// For x86_64 machines. (Modern PC's)
yarn dist -w --x64

// For x86 ONLY machines. (Legacy PC's)
yarn dist -w --ia32

::alert{type="warning"} On some low-end machines this process could take up to ~5 minutes. ::

Installing Cider

Your new Cider installation setup file is ready for you! You can find your setup executable in your cloned folder directory on your system in the subfolder dist/ and from there you'll see your new Setup file.

::alert{type="note" title="Success"} Congrats! You've successfully compiled your own build of Cider! ::

Example Plugin

Electron App Documentation

Electron BrowserWindow Documentation

Communicating with the Renderer instance from Main (IPC Main)

Communicating with main instance from the Renderer (IPC Renderer)

Cider offers a simple REST API to remotely control the app.

URL: http://localhost:9000/api/

Endpoints

Backend Development

Frontend Development

Publishing to GitHub

Once you have completed your plugin its time to publish! Create a new repository for the plugin and upload the files.

To have the theme indexed into Cider's built in plugin explorer, add cidermusicplugin as a topic on the repository.

Plugins from GitHub in Cider will display the repos README.md file within the Explore Plugins on GitHub page, so be sure to include some screenshots showing off your plugins.

Resources

Example Plugin

General Electron Documentation

BrowserWindow

IPC Main

IPC Renderer

Once you have completed your plugin its time to publish! Create a new repository for the plugin and upload the files.

To have the theme indexed into Cider's built in plugin explorer, add cidermusicplugin as a topic on the repository.

Cider Frontend API (CiderFrontAPI)

App Functions/Methods (app.*)

Cider Audio (CiderAudio)

These are some unsorted quirks and features about Cider that will be moved later

• Cider is built with the following frameworks and technologies

  • Electron

  • Vue 2

  • Express

  • EJS

  • MusicKit.js

  • Some components from Bootstrap 5 (mainly grids and modals)

  • Bootstrap Vue

  • Bootbox

  • Notyf

Attributes are applied to elements to expose app state information to CSS

Once you have completed your plugin its time to publish! Create a new repository for the theme and upload the files.

To have the theme indexed into Cider's built in theme explorer, add cidermusictheme as a topic on the repository.

theme.json files require the following properties:

• name: string - The name of the theme

• description: string - Brief description of the theme

• version: string - Version of the theme

• author: string - Theme authors

• github_repo: string - The source repository of the theme, this is required for Cider to automatically update the theme. Formatted <owner>/<repo_name>

• pack: array - (optional) Declare individual LESS files as styles within the package

  • Pack Object Format:

    • name: string - Name of the style

    • file: string - File name within the package / repo

    • description: string - Description of the style

If one does not already exist, create a new theme directory in the user data folder.

• Windows: %appdata%/Cider/themes

• Mac: ~/Library/Application Support/Cider/themes

• Linux: ~/.config/Cider/themes

Create a new folder in the themes directory with the name of your theme.

• This folder needs to contain the following files:

  • index.less - The main theme file

  • theme.json - Contains several properties for your theme

• You can clone a starter template from here: Theme Starter Template

In Cider, select the theme in the settings.

Cider has automatic hot reloading for themes in the userdata folder.

Useful Resources

• The default styles.less can be found in: src/renderer/style.less

• Less.js documentation

Resources in the theme can be accessed by their filenames in the theme folder.

Examples:

background: url("my_image.png")

@import url('another_less_file.less')