{"id":15639920,"url":"https://github.com/crushedpixel/plugalyzer","last_synced_at":"2025-10-14T07:04:03.631Z","repository":{"id":38385195,"uuid":"498551904","full_name":"CrushedPixel/Plugalyzer","owner":"CrushedPixel","description":"Command-line VST3, AU and LADSPA plugin host for easier debugging of audio plugins","archived":false,"fork":false,"pushed_at":"2025-01-25T21:43:38.000Z","size":117,"stargazers_count":100,"open_issues_count":8,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T06:01:36.510Z","etag":null,"topics":["audio-processing","juce-application"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CrushedPixel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-01T01:31:19.000Z","updated_at":"2025-03-26T05:39:47.000Z","dependencies_parsed_at":"2024-09-17T21:42:24.994Z","dependency_job_id":"62a405c1-8149-4bf5-a17d-c757243c05b7","html_url":"https://github.com/CrushedPixel/Plugalyzer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrushedPixel%2FPlugalyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrushedPixel%2FPlugalyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrushedPixel%2FPlugalyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrushedPixel%2FPlugalyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CrushedPixel","download_url":"https://codeload.github.com/CrushedPixel/Plugalyzer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608150,"owners_count":20965952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-processing","juce-application"],"created_at":"2024-10-03T11:28:13.774Z","updated_at":"2025-10-14T07:03:58.578Z","avatar_url":"https://github.com/CrushedPixel.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Plugalyzer\nA command-line VST3, AU, LADSPA and LV2 host meant to ease debugging of audio plugins and instruments by making it possible to run them in non-realtime outside of a conventional DAW.\n\nIt processes audio and MIDI from input files using the desired plugin, writing the result to an output file. \nPlugins with multiple input buses (such as sidechains) are supported.\n\n# Table of Contents\n- [Usage](#usage)\n - [Process audio files](#process-audio-files)\n - [Bus layouts](#bus-layouts) \n - [Parameter automation](#parameter-automation)\n - [Processing limitations](#processing-limitations)\n - [List plugin parameters](#list-plugin-parameters)\n - [Limitations](#limitations)\n- [Installation](#installation)\n\n# Usage\nThe general usage of plugalyzer follows the pattern `plugalyzer [command] [options...]`. \nUsing the `--help` flag, detailed usage information can be obtained for every command.\n\n## Process audio files\nThe `process` command processes the given audio and/or MIDI files using the given plugin in non-realtime,\nwriting the processed audio to an output file.\n\n| Option | Description | Required |\n|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|\n| `--plugin=\u003cpath\u003e` | Path to, or identifier of the plugin to use. | Yes |\n| `--input=\u003cpath\u003e` | Path to an audio input file.\u003cbr\u003eTo supply multiple input files, provide the `--input` argument multiple times. | Yes, unless `--midiInput` is set |\n| `--midiInput=\u003cpath\u003e` | Path to a MIDI input file. | No |\n| `--output=\u003cpath\u003e` | Path to write the processed audio to. | Yes |\n| `--overwrite` | Overwrite the output file if it exists.\u003cbr\u003eIf this option is not set, processing is aborted if the output file exists. | No |\n| `--sampleRate=\u003cnumber\u003e` | The sample rate to use for processing.\u003cbr\u003eOnly allowed if no audio input is provided.\u003cbr\u003eDefaults to 44100. | No |\n| `--blockSize=\u003cnumber\u003e` | The amount of samples to send to the audio plugin at once for processing.\u003cbr\u003eDefaults to 1024. | No |\n| `--outChannels=\u003cnumber\u003e` | The amount of channels to use for the plugin's output bus. Defaults to the amount of channels of the first input file. | No |\n| `--bitDepth=\u003cnumber\u003e` | The output file's bit depth.\u003cbr\u003eDefaults to the bit depth of the first input file, or 16 if no audio input is provided.\u003cbr\u003eMust be 8, 16, 24 or 32. | No |\n| `--paramFile=\u003cpath\u003e` | Specifies a JSON file to read parameter and automation data from. For more information, refer to [Parameter automation](#parameter-automation) | No | \n| `--param=\u003cname\u003e:\u003cvalue\u003e[:n]` | Sets the plugin parameter with the given name or index to the given value.\u003cbr\u003eBoth `name` and `value` can be quoted using single or double quotes.\u003cbr\u003eIf the `:n` suffix is given, the value is treated as a normalized value between 0 and 1, otherwise the string will be converted to the normalized value.\u003cbr\u003eTo set multiple parameters, supply the `--param` argument multiple times.\u003cbr\u003eUse the [`listParameters`](#list-plugin-parameters) command to list all available parameters. | No |\n| `--preset=\u003cpath\u003e` | Can be used to supply a `.vstpreset` file to VST3 plugins. | No |\n\nExample usage for a plugin with a main and a sidechain input bus:\n```shell\nplugalyzer process \\\n --plugin=/path/to/my/plugin.vst3 \\\n --input=main_input.wav \\\n --input=sidechain_input.wav \\\n --output=out.wav \\\n --param=\"Wet/Dry Mix\":0.2:n \\\n --param=Distortion:Off\n```\n\n### Parameter automation\nAside from the `--param` option, plugin parameters can also be supplied via JSON file using the `--paramFile` option. \nThis JSON file also allows for automation by supplying multiple keyframes that are linearly interpolated between.\n\nThe JSON file's main object contains an entry for each parameter.\n\nParameter values can either be a (floating-point) number or a string. \nNumbers are interpreted as normalized parameter values between 0 and 1. \nStrings are passed to the parameter's `getValueForText` function to convert them to normalized values. \nNote that string values can only be supplied for parameters that support text-to-value conversion.\n\nKeyframe times can be specified in the following formats:\n- a string containing an integer number is interpreted as a sample index.\n- a string suffixed with `s` is interpreted as an amount of seconds.\n- a string suffixed with `%` is interpreted as percentage relative to the total duration of the input files.\n\nThe following example illustrates the different options.\nPlease note that comments aren't supported by JSON, and need to be removed before using this example.\n\n```json5\n{\n \"Power\": \"On\", // no automation\n \"Cutoff\": 0.2, // no automation, normalized value\n\n // keyframe locations specified in samples:\n \"Dry/Wet Mix\": { \n // keyframe at 0 is not required, \n // it will use the value of the first keyframe until that keyframe is reached\n \"13024\": \"50%\",\n \"22050\": \"70%\",\n \"52316\": \"20%\"\n },\n\n // keyframe locations specified in seconds:\n \"Saturation\": { \n \"0s\": \"20%\", \n \"2.012s\": \"40%\",\n \"6.5s\": \"100%\"\n },\n\n // keyframe locations specified in percentage of total input duration:\n \"Detune\": {\n \"0%\": \"12\",\n \"50%\": \"-12\",\n \"100%\": \"12\"\n },\n\n // it's possible to mix keyframe time units:\n \"Fuzziness\": {\n \"0\": 0.15,\n \"50%\": 0,\n \"7s\": 1\n }\n}\n```\n\n### Bus layouts\nThe bus layout requested from the plugin is based on the audio input files.\nEach audio input file is provided to the plugin on a separate bus, each bus having the same amount of channels as the respective input file.\n\nPlugalyzer only supports a single output bus. The amount of channels can be specified using the `--outChannels` option.\nIf `--outChannels` is not set, it defaults to the amount of channels of the first audio input file.\nIf no audio input is provided (e.g. when testing MIDI instruments), the plugin's default output bus layout is used.\n\n### Processing limitations\n- Plugalyzer does not support showing plugin GUIs of any kind. Since processing is not done in real-time, this wouldn't be too useful, either way.\n- Only a single output bus is supported.\n\n## List plugin parameters\nThe `listParameters` command lists all available plugin parameters and their value range, as well as whether they support parameter values in text form.\n\n| Option | Description | Required |\n|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|\n| `--plugin=\u003cpath\u003e` | Path to, or identifier of the plugin to use. | Yes |\n| `--blockSize=\u003cnumber\u003e` | The processing block size to initialize the plugin with. This is only needed when a plugin doesn't support initialization with the default block size.\u003cbr\u003eDefaults to 1024. | No |\n| `--sampleRate=\u003cnumber\u003e` | The sample rate to initialize the plugin with. This is only needed when a plugin doesn't support initialization with the default sample rate.\u003cbr\u003eDefaults to 44100. | No |\n\nExample usage:\n```shell\nplugalyzer listParameters --plugin=/path/to/my/plugin.vst3\n```\n\nExample output:\n```shell\nLoaded plugin \"Black Box Analog Design HG-2\".\n\nPlugin parameters: \n0: Power\n Values: Off, On\n Default: On\n Supports text values: true\n1: Saturation Frequency\n Values: Low, Flat, High\n Default: Flat\n Supports text values: true\n2: Saturation In\n Values: Off, On\n Default: Off\n Supports text values: true\n3: Saturation\n Values: 0 % to 100 %\n Default: 50 %\n Supports text values: true\n\n[...]\n```\n\n### Limitations\n- Plugin parameters with a set of discrete values (i.e. not a floating-point range) that aren't correctly marked as such\n will not list all valid values. This issue arises, for example, when a JUCE plugin uses the deprecated\n `juce::AudioProcessorValueTreeState::Parameter` class where `juce::AudioParameterChoice` would be a better fit.\n\n# Installation\nThere are currently no pre-built binaries available for download, primarily because I do not have machines with all major operating systems available. \nTo compile this project yourself, clone it and build it via CMake. \nI recommend JetBrain's CLion for its excellent CMake support.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrushedpixel%2Fplugalyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrushedpixel%2Fplugalyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrushedpixel%2Fplugalyzer/lists"}