Main Page

From WaveSwissKnife

Revision as of 12:03, 17 December 2013 by Muriel (Talk | contribs)
(diff) ← Older revision | Current revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Wave Swiss Knife.


[edit] What is WSK (Wave Swiss Knife) ?

WSK is a command-line utility that processes WAV audio PCM files to apply audio filters, analysis tools or signals generation plugins.

WSK has been created to answer several points:

  • Process audio files for mastering engineers (noise gates, mixers...).
  • Test audio hardware bit-perfect fidelity, by providing many ways to compare and analyze WAV files.

[edit] What are the gold points of WSK ?

  • The main goal of WSK is to modify WAV files in a bit-perfect accuracy. It will process just needed data without altering unnecessary data. This idea came when realizing that even well-written softwares (Audacity) modify WAV files just by opening and saving them back with the exact same format.
  • WSK is made around a plugins architecture: creating new plugins is easy.
  • WSK is not limited in the number of channels and sample rate a WAV file contains.
  • WSK has a powerful Noise Gate plugin taking into account:
    • Amplitude of the noise.
    • Minimal duration that defines a silent part.
    • Attack and release of the signal after and before silent parts.
    • A FFT silence profile is used to detect if a residual signal might not lie in the silent parts.

[edit] What are the weaknesses of WSK ?

  • WSK is a command-line utility. No GUI, so this can be painful for some users.
  • WSK is mainly written in Ruby. This choice has been done to encourage productivity of development and maintenance, but the drawback is some slowness.
  • WSK is platform-dependent because costly plugins have been implemented in C for performance issues. This implies a step of compilation before using them from the source, or use a platform-dependent installer.
  • WSK processes static WAV files. It cannot be used to process streams or real-time signal flows.

[edit] Which WAV formats can WSK read ?

  • Type: Uncompressed PCM WAV files only.
  • Sample rate: Any.
  • Bit depths: 8, 16 and 24.
  • Number of channels: Any.

[edit] Which plugins are currently implemented ?

  • Analyze: Provide a statistical analysis of the WAV file.
  • ApplyMap: Apply a transformation map on the file.
  • ApplyVolumeFct: Modify a WAV file volume based on a mathematical function.
  • Compare: Compare 2 WAV files.
  • ConstantCompare: Check that a WAV file is constant.
  • Cut: Cut a specific part of a WAV file.
  • CutFirstSignal: Cut the first signal of a WAV file.
  • DCShifter: Add a constant to the values of samples.
  • DrawFct: Create a WAV file from a mathematical function. Useful to plot some processes.
  • FFT: Provide a Fast Fourier Transform analysis of the WAV file.
  • GenAllValues: Generate a WAV file containing all possible values for the required bit depth.
  • GenConstant: Generate a WAV file containing the same value for a given time.
  • GenSawtooth: Generate a WAV file containing a sawtooth signal for a given time.
  • GenSine: Generate a WAV file containing a sine wave for a given time.
  • Identity: Read an write a WAV file identical (useful for tests only).
  • Mix: Mix several WAV files.
  • Multiply: Multiply every sample by a given factor.
  • NoiseGate: Apply a noise gate on the file.
  • SilenceInserter: Insert silent section in a WAV file.
  • SilenceRemover: Remove leading and trailing silent sections.
  • VolumeProfile: Generate a mathematical function reflecting a WAV file's volume.

[edit] Installation

Please note that WSK uses the great math library GMP. If this library is not present in your system, WSK will try to install it automatically while installing the Gem. If this process fails (especially on Windows systems), you will have the extra step of installing and compiling it prior to installing WSK.

[edit] Using RubyGems

If you have RubyGems installed, you can install using:

> gem install WaveSwissKnife
Fetching: rUtilAnts- (100%)
Fetching: WaveSwissKnife- (100%)
Building native extensions.  This could take a while...
Successfully installed rUtilAnts-
Successfully installed WaveSwissKnife-
2 gems installed
Installing ri documentation for rUtilAnts-
Installing ri documentation for WaveSwissKnife-
Installing RDoc documentation for rUtilAnts-
Installing RDoc documentation for WaveSwissKnife-

[edit] Installation on Windows

Prior to installing WSK on Windows using RubyGems, your Windows environment has to get the following tools:

  • The Ruby programming language
  • A GNU development environment (gcc, ld, make)
  • A sh Shell
  • The GNU Tar utility

Here are the software components to be installed prior:

  • The Ruby language, GNU development environment and sh Shell can be installed using Rails Installer installer.
  • If you already have the Ruby language installed, The GNU development environment and sh Shell can be installed using the Ruby DevKit installer.
  • The GNU Tar utility is installed using the MingW installer (package msys-tar).

Here are the complete and detailed steps to achieve such an installation:

  1. If you don't have Ruby installed at all, go to Rails Installer page, download the Windows Ruby 1.9 download and install it. This will install Ruby and the Ruby DevKit at once.
  2. If you already have Ruby installed without the Ruby DevKit, go to the Ruby DevKit installer page and download the development kit for your Ruby version. Then install it in a directory, go there from yout command line and use commands ruby dk.rb init and ruby dk.rb install to complete its installation.
  3. Once you have Ruby and the Ruby DevKit installed, download the MingW installer, and install it (use an installation path without any space in names). Once in the Installation Manager where you select packages to be installed, select category "All packages" and scroll to the Package msys-tar (class bin). Right click on it and select "Mark for Installation". Then from the "Installation" menu, select "Apply Changes". Go through the installation process then exit.
  4. Next you have to add the paths to MingW executables in your PATH environment variable. 2 paths from your MingW installation directory have to be added: C:\MingW\bin and C:\MingW\msys\1.0\bin (replace C:\MingW with your MingW installation directory).
  5. Then you can install WSK using gem install WaveSwissKnife. This will download GMP library automatically and compile all necessary components for WSK to work. This step can be quite long to perform (a few minutes, be patient: the "Building native extensions. This could take a while..." part is really long), and your Antivirus software might get in the way (because this step compiles lots of files, your Antivirus will try to analyze all of them and report incorrectly suspicious files). It is recommended to temporarily disable your Antivirus software (especially Avast with its Sandbox feature) during this step.

If this fails or if you want a different GMP library version, you can try installing the GMP library with its development headers by yourself. gem install WaveSwissKnife first looks for an installed GMP library in your environment. If it fails to find one, it will download and install it itself.

[edit] Using source code

WSK also depends on the rUtilAnts library that need to be installed. You can either use gem install rUtilAnts or download its source code using GIT with git clone git://

Then you must checkout the WSK source code using GIT by issuing:

git clone git://

To use C compiled plugins, you need to execute:

ruby -w BuildExt.rb

Then you can use WSK by adding <WSKDir>/lib and <WSKDir>/ext to your Ruby library path and invoking <WSKDir>/bin/WSK.rb:

ruby -Ilib -Iext bin/WSK.rb

[edit] Usage

Once installed, you can use WSK this way:

> WSK.rb --help
WSK.rb [--help] [--debug] --input <InputFile> --output <OutputFile> --action <ActionName> -- <ActionOptions>
        --input <InputFile>          <InputFile>: WAVE file name to use as input
                                     Specify input file name
        --output <OutputFile>        <OutputFile>: WAVE file name to use as output
                                     Specify output file name
        --action <ActionName>        <ActionName>: Name of the action to process. Available Actions: Analyze, ApplyMap, ApplyVolumeFct, Compare, ConstantCompare, Cut, CutFirstSignal, DCShifter, DrawFct, FFT, GenAllValues, GenConstant, GenSawtooth, GenSine, Identity, Mix, Multiply, NoiseGate, SilenceInserter, SilenceRemover, VolumeProfile
                                     Specify the Action to execute
        --help                       Display help
        --debug                      Activate debug logs
Elapsed milliseconds: 2

WSK always takes 3 mandatory parameters: --input, --output, --action, defining an action to perform on an input WAV file to produce an output WAV file. Then depending on the action, there are additional parameters that can be specified further on the command-line, after a -- separator.


=> WSK.rb --input Sine.wav --output Dummy.wav --action VolumeProfile -- --function test.fct.rb --begin 0 --end -1 --interval 0.1s --rmsratio 0.5
Access Sine.wav
Write header in Dummy.wav
Execute Action VolumeProfile, reading Sine.wav and writing Dummy.wav using DirectStream output interface.
Dynamic range: [0.34 - 0.34] ([-9.28db - -9.28db] = 0.00db)
Elapsed milliseconds: 857

You can check each action's parameters on the Actions page.

[edit] Contact

If you want to help me improving WSK, or if you want more info on it, please send a mail to me.


Muriel Salvan

Personal tools