Install a plugin

Install, update and remove plugins on your MPC or Force with the MPC plugin installer app. The manual ways are at the bottom.

The easiest way to put plugins from the catalog on your MPC or Force is the MPC plugin installer: a small app you run on your computer. You pick plugins from a list (or drop zip files into it), press Install, and it does the rest: it checks every download, copies the plugins to your device, and restarts MPC once. You do not type any commands.

Installing plugins this way is unofficial. It edits MPC's settings file, so it needs root (SSH) access, which stock MPC OS does not offer. These plugins are for modded units. Back up your projects first and use it at your own risk.

What you need

• A first-generation MPC OS standalone device with a 32-bit ARM processor: Force, MPC Live and Live II, One, X and Key 61. The installer refuses anything else. Newer models are untested.
• Root SSH access to the device, and its IP address. The address is assigned by your router, so look it up on the device or in your router each time.
• A Windows, Mac or Linux computer on the same network as the device.
• Optional: an SD card or USB drive in the device, if you want plugins on it instead of on the internal drive (see "Where it goes" under step 5).

Check that you can reach your device

Find the IP address in the device's network settings, or in your router's list of connected devices. It can change, so check it each time. The app tests the connection for you when you press Connect, but you can try it first from a terminal (Terminal on a Mac, PowerShell on Windows 10 or later):

ssh root@<device-ip>

Answer yes to the fingerprint question. You should get a shell prompt on the device; type exit to leave. If this does not work, fix it first, because every way of installing uses it. In an SSH app such as Termius, the same test is adding a host with the IP and the username root, then connecting.

1. Download the app

Open the latest release and download the file for your computer from Assets:

Unpack it. You get one program, mpc-installer, and a short README.txt. The release also has a SHA256SUMS file if you want to check your download.

2. Start it

Double-click mpc-installer (or run it in a terminal). It prints a link and opens it in your browser. The page only works on your own computer.

The first time, your system warns that the program is from an unknown developer, because it is not signed:

• Windows: "Windows protected your PC": click More info, then Run anyway.
• Mac: it will not open on a double-click. Right-click the file, choose Open, then Open again. If that does not work, run xattr -d com.apple.quarantine mpc-installer in a terminal.
• Linux: run chmod +x mpc-installer if the file does not start.

3. Connect to your device

Type your device's IP address. Leave the password empty if you log in to the device with an SSH key; otherwise type the password. Press Connect. The page shows what it found: the device type, the plugin folders already on it, and the places plugins can go: the internal drive, and any SD card or USB drive that has a Synths folder, each with its free space. The password is used for that one connection and is not saved, and nothing about your device is stored on your computer.

4. Choose plugins

The list shows every plugin in the catalog that has a download, with its version, size and a short description. Tick the ones you want. A plugin that is already on your device is marked on the device, and if the catalog has a newer version than the one you installed, it shows update.

With many plugins, use the search box, the filters (kind, developer, whether it is already on the device or has an update) and the sort. What you tick stays ticked while you filter, and a bar at the bottom shows how many you have picked.

You can also drop zip files into the box under the list: plugins you downloaded yourself, or ones you built. A plugin marked Build it yourself in the catalog has no download, because it contains data from your own firmware; the Build page shows how to make the zip. The page checks each zip before it accepts it and tells you if something is wrong with it.

5. Install

Press Install… and read the question. Save your project on the device first: MPC is stopped and started again. Confirm, and watch the log. The app:

• downloads each zip and checks it against the checksum in the catalog, before it changes anything on your device (if a checksum does not match, nothing is installed);
• copies the plugins to the device, stops MPC once, runs each plugin's own installer, and starts MPC again;
• makes a backup of MPC's settings file first, and starts MPC again even if something fails.

Where it goes. If your device has an SD card or a USB drive with a Synths folder as well as its internal drive, an Install to choice appears above the Install button. The internal drive is the default. A card or drive works too, with three things to know: MPC must list its Synths folder as a content location, or a plugin's screen may not show (the page tells you if it does not); a drive that is formatted exFAT or FAT cannot store the symbolic links some plugins need (Crate Digger's bundled Python), so the app refuses those installs and tells you to use the internal drive; and if the drive is not in when MPC starts, its plugins drop out of MPC's plugin list until you register them again (see "Register plugin folders").

Some older releases have an installer that restarts MPC by itself, so MPC may restart more than once; the page says so before you confirm and the log shows it. Newer releases are installed in one go.

6. Use it

On the device, add the plugin to a track from the plugin browser: instruments under Instrument plugins, effects under Insert effects. Its screen appears in the plugin view, and the Q-Links follow the page. Save and reload a project once to make sure it comes back. If you turn on the manufacturer tab at the bottom of the browser, plugins are grouped by developer.

Update to a new version

Start the app, connect, and tick the plugin that shows update, then install as above. The new version replaces the old files in place and keeps the same plugin entry, so your projects still find the plugin. Files you added yourself (ROMs, kits, banks) are kept. A plugin you installed with an older release (the .so in /sdcard/vst) is replaced and your files are moved into its new folder in /sdcard/Synths.

The catalog shows a Compat number for each version. If it goes up, the parameters changed, and projects saved with an older version will sound different. Read the release notes before updating a plugin you use in finished songs. If MPC still runs the old version afterwards, remove every copy of the plugin from your project and insert it again.

Remove a plugin

In the app, open Remove plugins (step 4 on the page; click Show; plugins are grouped by the drive they are on), tick the plugin and press Remove…. MPC is stopped once, MPC's settings are backed up and the plugin is taken out of the plugin list, then its folder is deleted except your own files (ROMs, kits and dumps are kept), and MPC is started again. Projects that used the plugin still open, without it.

The app only removes plugins it can identify: ones from the catalog, or ones whose zip you have dropped into the page. For any other plugin it cannot tell which files in the folder are yours, so it lists the plugin but does not offer to remove it. Drop that plugin's zip to manage it, or remove it by hand.

Register plugin folders

A plugin only shows up in MPC once it is in MPC's plugin list. Folders you copied into a Synths folder yourself, plugins from other collections, or plugins MPC forgot (for example because a card was out when MPC started) are not in the list. In the app, open Register plugin folders (step 5 on the page; click Show). If something is waiting, a count appears next to the title and the list shows each folder and where it is. Press Register…: MPC is stopped once, its settings are backed up and the folders are added to the plugin list (entries whose plugin file is gone are dropped), and MPC is started again. Everything else in the list stays as it is.

Clean up old backups

Every install, removal and sync makes a copy of MPC's settings file on the device, and nothing deletes them, so they pile up (they are small). In the app, open Clean up old backups (step 6 on the page; click Show), choose how many of the newest to keep (10 is a good number) and press Delete older backups…. The newest backup is never deleted, MPC is not restarted, and nothing but the backups is touched.

If a plugin disappears after a restart

MPC keeps its whole plugin list in one place: the pluginList-arm list in its settings file, MPC.settings. Every way of installing plugins edits that same list, so one method can undo another. The plugin's files usually are still on the card; only its line in the list is gone. The usual causes:

• The settings file was edited while MPC was running. MPC holds its settings in memory while it runs and saves them itself, so a change made underneath it can be overwritten. Stop MPC first (systemctl stop acvs; the service is inmusic-mpc on Hakai-enabled systems), edit, then start it (systemctl start acvs). The app and the installers do this for you.
• Another tool rebuilt the whole list. Some community installers and scan scripts do not add one line: they write a new list from the plugin folders they find in the Synths folders (each folder with a plugin-meta.xml inside). A plugin that is not such a folder, for example one added by hand or installed by an older release with its .so in /sdcard/vst, drops off the list at the next scan. A release is such a folder if its zip has a portable/ folder inside, and a scan keeps it. Reinstall anything older with a release that has one.
• The settings file became invalid. After a broken edit MPC resets MPC.settings to its defaults, which empties the plugin list along with your other preferences. Restore a backup (below).
• The line points to a file that is not there: a plugin folder was moved or renamed, or the card it is on is not inserted.

Check what MPC has registered, and whether each file exists (on the device, over SSH):

grep -o 'file="[^"]*"' /media/az01-internal/Settings/*/MPC.settings | cut -d'"' -f2 |
    while read -r f; do [ -f "$f" ] && echo "ok       $f" || echo "MISSING  $f"; done

To get plugins back:

• Register the plugin folders in the app (step 5, "Register plugin folders"). If the plugin's folder is still on the device or its card, this adds its line back to the list without reinstalling anything. This is the quickest fix, and the right one when a card was out when MPC started.
• Install the plugin again (the current release) with the app. It adds its own line back and leaves every other plugin's line alone. This is the safest fix.
• Or restore a backup of the settings file. The app and the installers leave one next to the original each time they change it, named MPC.settings.bak-<plugin>-<date> (or bak-remove-…, bak-sync-…). List them newest first with ls -t /media/az01-internal/Settings/*/MPC.settings.bak-*, then stop MPC, copy the one you want over MPC.settings, and start MPC. A backup also brings back the preferences you had at that time.

Before you paste a command you found online into the device's shell, copy the settings file to your computer: scp "root@<device-ip>:/media/az01-internal/Settings/*/MPC.settings" . Any command that rebuilds, restores or resets that file replaces your whole plugin list.

If something goes wrong

• The app cannot connect. Check the IP address (it can change), that the device is on and on the same network, and that SSH is enabled. If you use a password, check it; otherwise the app only tries an SSH key in ~/.ssh that has no passphrase.
• The app says it cannot install on this device. It only installs to a 32-bit ARM MPC OS device where you are logged in as root.
• MPC shows default settings after the restart. The edited settings file was not accepted. Restore the backup the installer made, next to MPC.settings (see above).
• The plugin is not in the list. MPC reads its plugin list at startup. Check that the app's log ended with "Done", then see "If a plugin disappears after a restart" above.
• The plugin loads but has no screen. The skin goes in a /sdcard/Synths folder, and MPC must have that folder in its content locations. The installer warns if it does not.
• Silence, or default sounds. Some plugins need files you provide, such as ROMs or banks. Check the plugin's own page.

Ask in the community with the plugin's name, version, your device model and the installer's output (the log in the app).

Other ways to install

You do not need any of these if you use the app. They are here for people who prefer a terminal, or who cannot run the app. Each one installs the same release zips, with the same installer, so they can be mixed.

shasum -a 256 Name-1.2.0-mpc-armv7.zip      # macOS and Linux
certutil -hashfile Name-1.2.0-mpc-armv7.zip SHA256    # Windows

unzip Name-1.2.0-mpc-armv7.zip
scp -r Name-1.2.0 root@<device-ip>:/tmp/

ssh root@<device-ip> sh /tmp/Name-1.2.0/install.sh