yangdear/SoxSharp

SoxSharp

SoxSharp is a C# library that serves as a wrapper to SoX - the Sound eXchange tool. SoX is a cross-platform (Windows, Linux, MacOS X, etc.) command line utility that can convert various formats of computer audio files in to other formats. It can also apply various effects to these sound files and play and record audio files on most platforms.

How It Works

Initial Setup

When instantiating the Sox class, we pass to the constructor the location of the SoX executable to be used. Please note that, when SoX is executed, the directory of the application using the library will be used as the working directory, so any relative path included in both input and output files shall be relative to this directory.

Get File Information

Usage is pretty straightforward:

using (var sox = new Sox("sox.exe"))
{
  AudioInfo wavInfo = sox.GetInfo("test.wav");
  Console.WriteLine(wavInfo);
}

This is the same as executing sox --info test.wav. SoxSharp parses the SoX output and fills an AudioInfo instance with the retrieved information.

File Conversion

The simplest way to perform an audio conversion is to just call the Sox.Process method with both input and output files:

using (var sox = new Sox("sox.exe"))
{
  sox.Process("test.wav", "test.mp3");
}

The previous code will launch SoX with 'test.wav' as input file and 'test.mp3' as output file (the equivalent of executing SoX with the following parameters: sox test.wav test.mp3).

To force the output to be encoded with MP3 format (instead of letting SoX to guess it from the output file extension) and use a sample rate of 32 KHz:

using (var sox = new Sox("sox.exe"))
{
  sox.Output.Type = FileType.MP3;
  sox.Output.SampleRate = 32000;

  sox.Process("test.wav", "test.mp3");
}

This is equivalent to call SoX with the following parameters: sox test.wav --type mp3 --rate 32000 test.mp3.

SoX global options can be set through their respective properties in the Sox class. Format options to be applied to the output can be stablished through its respective properties in Sox.Output.

Format options to be applied to the input are specified passing an InputFile instance to the Sox.Process method (instead of an input file string):

using (var sox = new Sox("sox.exe"))
{
  sox.Output.Type = FileType.MP3;
  sox.Output.SampleRate = 32000;

  InputFile testInput = new InputFile("test.wav");
  testInput.Volume = 0.8;

  sox.Process(testInput, "test.mp3");
}

This is equivalent to call SoX with the following parameters: sox --volume 0.8 test.wav --type mp3 --rate 32000 test.mp3.

Applying Effects

One or multiple effects can be added so they will applied to the output file:

using (var sox = new Sox("sox.exe"))
{
  sox.Output.Type = FileType.MP3;
  sox.Effects.Add(new VolumeEffect(10, GainType.Db));
  sox.Effects.Add(new HighPassFilterEffect(500));

  sox.Process("test.wav", "test.mp3");
}

Currently not all SoX effects have been implemented into SoxSharp. To see which effects are supported, please read this issue.

Playing and Recording

To record audio from the default audio device, use the Sox.Record method specifying the output file name:

sox.Record("test_record.mp3");

Analogously, Sox.Play allows to send an input file to the default audio device. In this case, the input file can be expressed as an file name string or a InputFile instance.

The same results can be obtained if calling Sox.Process using --default-device as output (for playing) or input (for recording) file.

Error Handling

If any requested SoX operation is unable to be processed, either because SoX process can't be launched or beacuse it generates an error, a SoxException with details about the error will be thrown.

Events

You can subscribe to receive any log message generated by SoX through the OnLogMessage event. Please note that log messages of type FAIL will not be reported through this event but as exceptions, as stated in Error Handling.

// Subscribe to OnLogMessage.
sox.OnLogMessage += sox_OnLogMessage;

void sox_OnLogMessage(object sender, LogMessageEventArgs e)
{
  Console.WriteLine(e.LogLevel + ": " + e.Message);
}

Also, while executing a Process call you can obtain updated progress information about the operation subscribing to the OnProgress event:

// Subscribe to OnProgress event before calling Process method.
sox.OnProgress += sox_OnProgress;

void sox_OnProgress(object sender, ProgressEventArgs e)
{
  Console.WriteLine("{0} ({1}% completed)", e.Processed.ToString(@"hh\:mm\:ss\.ff"), e.Progress);
}

Concurrency

All the work is done in the calling thread. Each Sox class instance can handle only one process at the same time, and will block the calling thread until finished. You are responsible for creating any worker thread if needed.

The library provides two different methods to cancel any work that is in progress:

Calling the Abort() method of the Sox class.
Inside the OnProgress event handler. ProgressEventArgs provides a boolean Abort member that can be set to true to end the current work.

Library Reference

A detailed description of all components of the library is available at the repository wiki.