Build Your Own Audion Plugin

Prerequisites

Before building a plugin, make sure you have the basics:

• Audion installed and running
• Basic JavaScript knowledge (variables, functions, objects)
• A text editor or IDE (VS Code recommended)
• Git for distributing your plugin (optional)

Plugin Manifestplugin.json

Every plugin begins with a plugin.json manifest. This file tells Audion who made the plugin, what it does, what permissions it needs, and where the code lives.

Required Fields

Optional Fields

Example Manifest

{
  "name": "Play Counter",
  "version": "1.0.0",
  "author": "Audion Team",
  "description": "Tracks how many times each song has been played",
  "type": "js",
  "entry": "index.js",
  "permissions": [
    "player:read",
    "storage:local",
    "ui:inject"
  ],
  "category": "library",
  "tags": [
    "stats",
    "play-count",
    "analytics"
  ],
  "license": "MIT"
}

Plugin Structure

Audion plugins follow a simple directory structure. The folder name should be lowercase with dashes (kebab-case).

plugin-examples/
└── your-plugin-name/
    ├── plugin.json       # Plugin manifest (required)
    ├── index.js          # Main plugin code — entry point
    ├── icon.png          # Plugin icon (optional)
    └── README.md         # Documentation (optional)

JavaScript Plugin Pattern

Use an Immediately Invoked Function Expression (IIFE) to avoid polluting the global namespace:

(function () {
  'use strict';

  const YourPlugin = {
    name: 'Your Plugin Name',
    someState: null,

    // Called once when plugin is loaded
    init(api) {
      this.api = api;
      console.log('[YourPlugin] Initialized!');
    },

    // Called when plugin is enabled
    start() {
      const track = this.api.player.getCurrentTrack();
      if (track) {
        console.log('Now playing:', track.title);
      }
    },

    // Called when plugin is disabled
    stop() {
      console.log('[YourPlugin] Stopped');
    },

    // Called when plugin is unloaded
    destroy() {
      // Clean up intervals, listeners, UI elements
      console.log('[YourPlugin] Cleaned up');
    }
  };

  // Register globally — required!
  window.YourPlugin = YourPlugin;
  window.AudionPlugin = YourPlugin;
})();

Lifecycle Hooks

Audion calls specific methods on your plugin object during its lifecycle:

Available Permissions

Permissions control what your plugin can access. Request only what you need — users review these before enabling.

Example

"permissions": ["player:read", "storage:local"]

Storage API

Plugins with the storage:local permission can persist data between app restarts.

// Save data
this.api.storage.set('playCount', { track1: 5, track2: 12 });

// Read data
const counts = this.api.storage.get('playCount');
// → { track1: 5, track2: 12 }

// Delete data
this.api.storage.remove('playCount');

Storage is namespaced per plugin — data from "Play Counter" won't conflict with "Theme Customizer".

UI Injection

Plugins with the ui:inject permission can insert custom UI elements into the app. Use it sparingly and clean up in destroy().

// Add a custom button to the player bar
const btn = document.createElement('button');
btn.textContent = 'My Plugin';
btn.onclick = () => alert('Hello from plugin!');
document.querySelector('.player-bar')?.appendChild(btn);

// Store reference for cleanup
this.myButton = btn;

// In destroy():
destroy() {
  if (this.myButton) {
    this.myButton.remove();
    this.myButton = null;
  }
}

Testing Locally

Once your plugin folder is ready, test it in Audion:

1. Copy your plugin folder to the plugin-examples/ directory in Audion (or the plugins directory in your Audion data folder)
2. Open Audion and go to the Plugins page
3. Your plugin should appear in the list. Click Enable to activate it
4. Open the Developer Console (Ctrl+Shift+I) to see your console.log output
5. Reload the plugin after code changes (disable → enable)

Debugging Tips

• Check the browser console for errors
• Verify your plugin.json is valid JSON
• Make sure window.AudionPlugin is set
• Ensure all referenced files exist in your plugin folder

Publishing to the Registry

The Audion marketplace auto-indexes plugins via GitHub repository topics. No manual PR needed — just push code and add the topic.

Step 1: Create a Public GitHub Repository

• Push your plugin code to a public GitHub repo
• Ensure plugin.json and entry file are at the repository root
• Include a README.md so users know what the plugin does

Step 2: Add the Topic

Open your repo on GitHub → Settings → scroll toTopics → add audion-plugins.

The audion-plugins registry action scans for repos with the audion-plugins topic. If your repo has valid .json manifest files (starting withplugin.json at the root), it gets indexed automatically.

Validation Checklist

Before adding the topic, confirm your repo has:

• A valid plugin.json at the root
• All referenced files exist (entry point, icons, etc.)
• A plugin.json with valid JSON syntax and required fields
• A public repo (private repos won't be indexed)

Update a Published Plugin

Push changes to your repo. The action re-indexes on the next scan — no topic changes needed.

Distribution via Deep Link

Each plugin on the marketplace has an Install in Audion button that opens the app and prompts the user to install. You can link directly to your plugin from anywhere.

Deep Link Format

audion://install-plugin?url=https://github.com/your-username/your-plugin

How It Works

1. User clicks the link — Audion opens (or comes to front)
2. A confirmation dialog asks: "Do you want to install the plugin from repository?"
3. Audion fetches plugin.json from the repo, downloads the entry file and icon
4. Plugin is installed and ready to enable in the plugin manager