README.md

Ada Wavefile Library

Version 2.0.0

Introduction

This Library contains a Wavefile Reader & Writer written in Ada 2012. It supports reading and writing of wavefiles, including the following features:

• Mono, stereo and multichannel audio.
• Audio samples with following bit depths:
  • 16/24/32/64-bit PCM
  • 32/64-bit floating-point PCM
• Wave-Format-Extensible format (WAVE_FORMAT_EXTENSIBLE)

This library also includes support for PCM buffers in floating-point and fixed-point formats, as well as the automatic conversion between the data types used for the PCM buffer and the wavefile, which might have different formats (floating-point or fixed-point) or precisions (e.g., 16 bits or 64 bits).

In addition, following features are available:

• Support for parsing known GUIDs
• Support for parsing RIFF chunks
• Support for sample positioning and timing information

See the CHANGELOG file for a comprehensive list of features.

To contribute to this project, please refer to the guidelines described in the CONTRIBUTING file.

License & Copyright

As indicated in the LICENSE file, this Library is available "as is" under MIT License. Please refer to that file for all licensing conditions. Unless stated otherwise, the copyright is held by Gustavo A. Hoffmann.

Supported Platforms

This Library has been tested with following compilers and platforms:

• GNAT FSF 7, 8, 9 and 10 for Linux;
• GNAT Community 2020 for Linux, Windows and macOS.

Setting Up the Library

Cloning the source-code

You can clone the source-code of the Library and its dependencies using these commands from the root directory of your project:

mkdir deps

(cd deps && git clone https://github.com/Ada-Audio/audio_base )
(cd deps && git clone https://github.com/Ada-Audio/audio_wavefiles )

Note that you can use the --branch option to retrieve a specific version — for example: --branch 2.0.0.

Another method is to use git submodules:

git submodule add https://github.com/Ada-Audio/audio_base ./deps/audio_base
git submodule add https://github.com/Ada-Audio/audio_wavefiles ./deps/audio_wavefiles

Integration with your project

This section describes how to manually integrate the Library into your GPRbuild project. If you're using ALIRE, please refer to the next section.

You can include the Library in your GPRbuild project by adding the following line:

with "audio_wavefiles.gpr";

You can use GPRbuild to build your project with the Library. Don't forget to set the path to the GPRbuild projects using the environment variable GPR_PROJECT_PATH:

# Set path to audio_base and audio_wavefiles
export GPR_PROJECT_PATH="$(cd deps/audio_base && pwd):$(cd deps/audio_wavefiles && pwd)"

gprbuild

Using ALIRE

If you're using ALIRE (the Ada LIbrary REpository), this section shows how you can integrate the Library to your project using the ALIRE environment. These are the prerequisites:

1. You have cloned the source-code of the Library and its dependencies using one of the methods described above.

2. You have initialized your project for ALIRE (using alr init --bin or similar).

You can now integrate the Library and its dependencies to the ALIRE environment using these commands:

alr with audio_base      --use $(cd deps/audio_base      && pwd)
alr with audio_wavefiles --use $(cd deps/audio_wavefiles && pwd)

For the remaining of this section, we'll assume that your ALIRE project is called wavefile_test. Just replace this name with the actual name of your project wherever it's appropriate.

Now, let's say you have the following main application in ./src/wavefile_test.adb:

with Ada.Text_IO;     use Ada.Text_IO;
with Audio.Wavefiles; use Audio.Wavefiles;

procedure Wavefile_Test is
   WF : Wavefile;
begin
   WF.Create (Out_File, "test.wav");

   if WF.Is_Open then
      Put_Line ("Created output wavefile.");

      WF.Close;
   end if;
end Wavefile_Test;

You can build the project using ALIRE:

alr build

And run it with this command:

./alire/build/bin/wavefile_test

Using the Library

To use the Library, you have to add a reference to the Wavefiles package to your source-code file:

with Audio.Wavefiles; use Audio.Wavefiles;

Then, you can open and close a wavefile:

   WF            : Wavefile;
begin
   WF.Open (In_File, "test.wav");

   WF.Close;

Also, you should instantiate at least one of the PCM I/O packages. To do that, you could reference, for example, the generic PCM I/O package for floating-point types:

with Audio.Wavefiles.Generic_Float_PCM_IO;
use  Audio.Wavefiles.Generic_Float_PCM_IO;

You can then instantiate this package for reading, for example:

   type Float_Array is array (Positive range <>) of Float;

   package PCM_IO is new Audio.Wavefiles.Generic_Float_PCM_IO
     (PCM_Sample    => Float,
      Channel_Range => Positive,
      PCM_MC_Sample => Float_Array);
   use PCM_IO;

You can now read data from the wavefile:

   loop
      declare
         PCM_Buf : constant Float_Array := Get (WF);
      begin
         exit when WF.End_Of_File;
      end;
   end loop;

For a list of source-code examples for various use-cases — starting from the simplest ones to more complicated use-cases —, please refer to the cookbook.

Roadmap

These features are on the list for future versions of this Library:

• Support for Broadcast Wave Format
• Support for RF64
• Support for Audio Definition Model
• Support for Serial Representation of the Audio Definition Model