# Example charm manifest: IKANDY

The manifest: [app.ikandy.json](https://mbxhub.com/downloads/examples/app.ikandy.json)

A charm manifest is a small JSON file that tells MBXHub about a charm: what it is called, what
it looks like, and what happens when you click it. This example describes **IKANDY**, a desktop
application.

## What it does

It puts IKANDY in 3 places you can start it from, without leaving what you are doing:

1) a link in MusicBee's Tools menu Tools: MBXHub: IKANDY 
2) as a charm that can be shown on the dashboard
3) as a button in the HUD and the overlay Charm Bar. (Ctrl + Alt + B)

All three start the same application. The manifest launches IKANDY, it does not install it, so
[IKANDY](https://ikandy.app/) has to be on the machine already — it is on
[Steam](https://store.steampowered.com/app/4813240/IKANDY), with a free tier.

## Using it

1. Download [app.ikandy.json](https://mbxhub.com/downloads/examples/app.ikandy.json).
2. Put the file in your MBXHub `charms` folder:
   - normal install: `%APPDATA%\MusicBee\MBXHub\charms\`
   - portable install: `<MusicBee folder>\AppData\MBXHub\charms\`
3. Restart MusicBee. The Tools menu is built when MusicBee starts.

## Anatomy of the example

```json
{
  "id": "app.ikandy",
  "kind": "proc",
  "label": "IKANDY",
  "publisher": "L&R Entertainment LLC",
  "version": "0.1.0",
  "icon": "🍬",
  "launch": "steam://run/4813240",
  "launchFallback":"drive:/pathto/IKANDY/IKANDY.exe",
  "expand": [
    { "label": "IKANDY", "icon": "🍬", "placement": "menu",    "action": "launch", "msg": "Starting IKANDY…" },
    { "label": "IKANDY", "icon": "🍬", "placement": "rail",    "action": "launch", "msg": "Starting IKANDY…" },
    { "label": "IKANDY", "icon": "🍬", "placement": "overlay", "action": "launch", "msg": "Starting IKANDY…" }
  ]
}
```

### Who the charm is

| Field       | In this example         | What it means                                                                                                                                       |
| ----------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | `app.ikandy`            | The charm's unique name. Use a publisher-style dotted name such as `com.example.thing`; a charm that registers with the hub is refused without one. |
| `kind`      | `proc`                  | Where the charm's code lives. `proc` is a program on this machine. Leave it out and the charm is a `page` (HTML that MBXHub hosts).                 |
| `label`     | `IKANDY`                | The name people see.                                                                                                                                |
| `icon`      | `🍬`                    | The emoji on the button.                                                                                                                            |
| `publisher` | `L&R Entertainment LLC` | Who made it. Free text.                                                                                                                             |
| `version`   | `0.1.0`                 | The charm's own version. Free text; MBXHub shows it but does not compare versions.                                                                  |

### What it starts

| Field            | In this example                   | What it means                                                                                                                                                                                                                                                                                                    |
| ---------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `launch`         | `steam://run/4813240`             | The first thing to start: here, IKANDY through Steam. A URL scheme is handed to Windows as written.                                                                                                                                                                                                              |
| `launchFallback` | "drive:/pathto/IKANDY/IKANDY.exe" | Tried only when the first one can't start, for example when Steam isn't installed. **NOTE**: you may need to replace it with the real path, such as `"C:\\Program Files (x86)\\Steam\\steamapps\\common\\IKANDY\\IKANDY.exe"`  [note: `/` or `\\` is accepted as a path delimiter] |



Successful dispatch never starts both targets.

### Where the button appears

`expand` lists the charm's buttons. Each entry says **where** it appears (`placement`) and
**what** clicking it does (`action`). This example puts the same button in three places:

| Manifest says            | Where you see IKANDY                     |
| ------------------------ | ---------------------------------------- |
| `"placement": "menu"`    | MusicBee's **Tools > MBXHub > IKANDY**   |
| `"placement": "rail"`    | The charm rail on the dashboard web page |
| `"placement": "overlay"` | The HUD and the Charm Bar (Ctrl+Alt+B)   |

In every entry:

- `action: "launch"` starts the charm, using `launch` and then `launchFallback`. The word takes no
  target of its own; the targets live only at the top of the manifest.
- `msg` is the status text shown when you click.

## When a launch is allowed

- Launching happens only from the machine running MusicBee.
- A manifest you put in your own `charms` folder, with no registration, may launch its targets.
- Some URL schemes are always refused, including `http`, `https`, `file` and anything starting `ms-`.
- If the operator narrows the allowed schemes, `steam` has to be on that list.
- If **Require registration for charms** is on (MBXHub settings, API Access tab), a manifest that
  was never registered does not launch.

## More

The full manifest reference is in [llms.txt](https://mbxhub.com/llms.txt), under **Manifest
fields**, **Manifest registration fields** and **Placements, and how an activation reaches a charm**.