Plugins

Custom Plugins

i3-volume supports a plugin system that allows you to extend functionality with custom notification methods and output formats. The plugin infrastructure is designed to easily support additional plugin types in the future.

Plugin System Overview

The plugin system is organized by plugin type, with each type having its own directory:

• ~/.config/i3-volume/plugins/notify/ - Notification plugins
• ~/.config/i3-volume/plugins/output/ - Output format plugins

Notification Plugins

Notification plugins allow you to create custom notification methods that integrate with any notification system or service.

Creating a Notification Plugin

1. Create the plugin directory (if it doesn't exist):

   mkdir -p ~/.config/i3-volume/plugins/notify

2. Create your plugin script:

   # Create the plugin file
   touch ~/.config/i3-volume/plugins/notify/myplugin
   chmod +x ~/.config/i3-volume/plugins/notify/myplugin

3. Implement the plugin function:

   #!/bin/bash
   notify_volume_myplugin() {
       local vol=$1      # Volume (0-100)
       local icon=$2      # Icon path (may be empty)
       local summary=$3   # Summary text
       local body=${*:4}  # Body text (may be empty)
   
       # Your custom notification implementation here
       # Example: Send to a custom service
       curl -X POST https://api.example.com/notify \
           -d "volume=$vol" \
           -d "summary=$summary" \
           -d "body=$body"
   }

Using a Notification Plugin

Once created, use your plugin with the -N option:

volume -N myplugin up 5

Or set it in your configuration file:

NOTIFICATION_METHOD="myplugin"

Example: File-based Notification

#!/bin/bash
notify_volume_filelog() {
    local vol=$1
    local summary=$3
    echo "$(date): $summary (Volume: $vol%)" >> ~/.volume-log.txt
}

Example: Webhook Notification

#!/bin/bash
notify_volume_webhook() {
    local vol=$1
    local summary=$3
    local body=${*:4}

    curl -X POST "$WEBHOOK_URL" \
        -H "Content-Type: application/json" \
        -d "{\"volume\":$vol,\"summary\":\"$summary\",\"body\":\"$body\"}"
}

Output Format Plugins

Output format plugins allow you to create custom output formats for integration with status bars, scripts, or other tools.

Creating an Output Format Plugin

1. Create the plugin directory (if it doesn't exist):

   mkdir -p ~/.config/i3-volume/plugins/output

2. Create your plugin script:

   # Create the plugin file
   touch ~/.config/i3-volume/plugins/output/myformat
   chmod +x ~/.config/i3-volume/plugins/output/myformat

3. Implement the plugin function:

   #!/bin/bash
   output_volume_myformat() {
       # Query volume state internally
       local vol
       vol=$(get_volume 2>/dev/null || echo "0")
   
       # Your custom output format
       if is_muted 2>/dev/null; then
           echo "🔇 MUTED"
       else
           printf "🔊 %3d%%" "$vol"
       fi
   }

Using an Output Format Plugin

Use your plugin with the output command:

volume output myformat

Example: Simple Text Format

#!/bin/bash
output_volume_simple() {
    local vol
    vol=$(get_volume 2>/dev/null || echo "0")
    echo "Volume: $vol%"
}

Example: JSON Format with Additional Data

#!/bin/bash
output_volume_enhanced() {
    local vol muted sink_name
    vol=$(get_volume 2>/dev/null || echo "0")
    muted=$(is_muted 2>/dev/null && echo "true" || echo "false")
    sink_name=$(get_node_display_name 2>/dev/null || echo "unknown")

    echo "{\"volume\":$vol,\"muted\":$muted,\"sink\":\"$sink_name\"}"
}

Available Functions

When writing plugins, you have access to the same helper functions that i3-volume uses internally:

Volume Functions

• get_volume() - Get current volume (0-100)
• is_muted() - Check if volume is muted
• get_node_display_name() - Get sink/source display name
• get_balance() - Get audio balance

Microphone Functions

• get_mic_volume() - Get microphone volume (0-100)
• is_mic_muted() - Check if microphone is muted

Helper Functions

• empty "$var" - Check if variable is empty
• not_empty "$var" - Check if variable is not empty
• error "message" - Print error message

Listing Available Plugins

List all available notification methods (including plugins):

volume notifications

List all available output formats (including plugins):

volume outputs

Plugin Examples

Example plugins are available in the examples/ directory:

• examples/plugin.example - Notification plugin template
• examples/plugin.output.example - Output format plugin template

Troubleshooting

Plugin Not Found

If your plugin isn't being discovered:

1. Check the directory structure: Plugins must be in the correct subdirectory (plugins/notify/ or plugins/output/)
2. Check file permissions: Plugins must be executable (chmod +x)
3. Check the function name: The function name must match the pattern:
   • Notification: notify_volume_<plugin-name>()
   • Output: output_volume_<plugin-name>()

Plugin Loading Errors

If you see errors when loading a plugin:

1. Check syntax: Run bash -n your-plugin to check for syntax errors
2. Check dependencies: Ensure any external commands your plugin uses are available
3. Check function definition: The function must be defined exactly as expected

Debugging

To debug plugin issues, you can add debug output:

notify_volume_myplugin() {
    local vol=$1
    echo "DEBUG: Volume is $vol" >&2  # Output to stderr
    # ... rest of plugin
}

Best Practices

1. Error handling: Always check if required functions or commands are available
2. Exit codes: Return appropriate exit codes (0 for success, non-zero for failure)
3. Quiet operation: Avoid unnecessary output unless debugging
4. Documentation: Comment your plugins for future reference
5. Testing: Test plugins thoroughly before using them in production

Future Plugin Types

The plugin system infrastructure is designed to support additional plugin types in the future. The architecture makes it easy to add new types like:

• Hook plugins (pre/post command execution)
• Custom status bar formats
• Integration plugins for specific services

Check the main README for updates on new plugin types.