PION Examples

Echo

This plug-in demonstrates a simple echo effect with a waveform visual when previewed.

Click here then choose "View Page Source" in the browser see the source code

The first step is to create an the EffectData object with all the details the PION API requires (properties, parameters, presets, and icon):

properties: {
    api: 1000,                              // PION API version
    id: 'com.goldwave.pion.echodemo',       // Unique ID for this effect (could be a UUID)
    type: 'effect',                         // Type of plug-in: effect, converter, analyzer...
    media: 'audio',                         // What type of media is processed: audio, video, image
    label: 'Echo',                          // Effect name to show to the user
    version: 1000,                          // Effect version (required for preset compatibility)
    apply: false,                           // Effect changes settings on-the-fly and does not require an Apply button
    streamable: true,                       // Can the effect be streamed/chained with other effects (no seeking)
    scan: false,                            // Requires preprocess scan
    clipboard: 'no',                        // Requires clipboard: 'no', 'yes' or 'optional'
    ui: 'yes',                              // Effect has a UI, 'no' = no UI required, 'yes' = in browser, 'host' = host must create one
    size: { width: 375, height: 330 },      // (optional) UI window size recommended for host
    channels: 0,                            // Number of channels supported (0 = any)
    cache:  [                               // (optional) Effect can be cached on local device by storing these additional files
        'pion.js'
    ],
    help: 'https://goldwave.com/pion/examples.html#echo'    // Where to get more help (if not included)
},

// Parameters are all the effect settings
parameters: {
    list: [
        { name: 'volume', label: 'Volume', unit: 'dB', minimun: -200, maximum: 10, step: 0.1, value: -6 },
        { name: 'delay', label: 'Delay', unit: 'ms', minimun: 1, maximum: MaxDelay, step: 1, value: 250 }
    ],
},

// Presets list predefined settings the user can select.  The host may create it's own list.
presets: {
    list: [
        { label: 'Half second, half volume', values: { volume: -6, delay: 500 } },
        { label: 'One second, loud', values: { volume: -1, delay: 1000 } }
    ],
}

// Icon is an image that is shown to the user in the host, usually on a toolbar or menu
icon: { url: 'effecticon.png' } // or 'data:....'

Next we need to set up the connection with the host. To do that we can set a window.onload event handler or add an onload handler to the <BODY> element. This function must call PionConnect with the EffectData object. An effect object is returned.

{
    effectData: effectData,     // EffectData as set above
    socket: 0,                  // Communication socket
    state: PionState.unknown,   // Current effect state
    language: 'en',
    stream: '',                 // The stream to configure or data received (main, clipboard)
    config: {
            rate: 0,            // Sampling rate in Hz (integer)
            channels: 0,        // Number of channels in the audio data (interleaved)
            channelMask: 0,     // A bitmask indicating which channels to process
            start: 0,           // The start time of the selection (sample offset, optional)
            finish: 0,          // The finish time of the selection (sample offset, optional)
    },
    callback: {
            OnConnect: null,
            OnCommand: null,
            OnData: null,
            OnError: null,
            OnClose: null,
    },				
    data: {}                    // Any data needed for the effect callbacks
}

Now we need to set the OnConnect, OnClose, OnError, OnCommand, and OnData handlers. We also need to set data to anything we might need when processing the callbacks. OnCommand sets, gets, and resets parameters. It also configures the effect to match the config values. OnData processes the effect. It receives the effect object and a Float32Array of interleaved audio samples. See the example source code for details.

Mix

This plug-in demonstrates accessing clipboard audio to mix with the main stream. Here are some of the changes compared to the Echo effect:

Sets the clipboard value in the EffectData object to 'yes'
Adds the clipboard to our effect data object
Resets the cliboard state in the OnCommand handler
Changes the OnData handler to handle both 'main' and 'clipboard' streams

Click here, then choose "View Page Source" in the browser see the source code

Scan

This plug-in demonstrates scanning the entire audio stream first to obtain peak information, then displaying that information and using it when adjusting the peak. Here are some of the changes compared to the Echo effect:

Sets the scan value in the EffectData object to true
Changes the OnData handler to handle both main and scan streams.

The host streams all the audio to the scan stream first.

Click here then choose "View Page Source" in the browser see the source code

Plug-in Over Network, PION, PIONAPI and PION logo are trademarks of GoldWave Inc.