Overview
--------

Libwaveform attempts to provide versatile easy-to-use interactive display
of audio waveforms for Gtk+-2 and X11 applications. Suitable for anything from simple
display, up to a full digital audio workstation.

Efficiency:

* audio and peak data is handled in blocks to get reasonable performance with large files.
* opengl hardware features are used where available.
* multi-level caching.
* the view can be changed (size, position, magnification) at little cost.
* in many cases drawing can be done repeatedly with virtually no cpu load.

Multi-level caching is provided:

* peak files are saved to disk roughly following freedeskop.org standards. (Ardour session peak files are also supported.)
* peak files are cached in ram at multiple resolutions.
* audio is cached in ram for use at high resolutions.
* peaks are stored as OpenGl 2D textures in graphics hardware.
* peaks are stored as OpenGl 1D textures for use with shader programs.
* rendered and filtered images are stored as OpenGl FBO's.

Magnification and translation transitions are animated.

There are 4 main ways of using libwaveform:

1. the WaveformView Gtk widget
2. with OpenGL using the WaveformActor interface
3. rendering to a GdkPixbuf
4. rendering to an Alphabuf

Requirements:

- Gtk2
- GtkGLExt/GLX/SDL
- Libsndfile/FFmpeg
- OpenGl (recommended)


Status
------

Main functionality is now in place, but some areas are subject to improvement. There
are no known serious bugs so please report any you find. Feedback is also needed
on api, documentation, visuals etc.

An API review needs to be undertaken before a release is made.

As well as GTK, support for other platforms is being added. Currently there is
some support for SDL and GLX. Please note that there is no support for QT, though
it would be simple to support if someone was interested.

Testing:
Has been fully tested with Gallium 0.4 on Radeon RV530, RV620 and Cedar, and Intel 945 and HD3000.
Other hardware is less well tested and wider testing is needed.

If you are able to help testing, please start with running test/view_test.
To compile the test programs you need to run configure with '--enable-test'.


WaveformView
------------

The easiest way to use libwaveform is via the WaveformView Gtk widget.

The widget will show the complete audio file and can be panned and zoomed
down to sample level.

To use the widget:
```c
	WaveformView* waveform = waveform_view_new(NULL);
	waveform_view_load_file(waveform, "myfile.wav");
```
(then pack and show the widget as normal)	

For a demonstration of usage, see: test/view_test.c


WaveformActor
-------------

The WaveformActor interface can be used to show a waveform on an
existing GtkGLExt drawing area. It is designed for use in editors
and audio production tools.

OpenGl shaders will be used if available, otherwise it will fallback
to using 8 bit textures.

WaveformActor's share a common WfContext object.
The context has the following directly settable properties:
```c
	uint32_t sample_rate
	float    bpm
	float    samples_per_pixel
	int64_t  start_time
	float    v_gain
```

For a demonstration of usage, see: test/actor_test.c

Support for different peak formats is provided by 'loaders'. As
well as the default peak file loader, an Ardour session loader is
provided:
```c
	waveform_set_peak_loader(wf_load_ardour_peak);
```
or you can specify your own loader.


GdkPixbuf
---------

Libwaveform provides the function waveform_render_peak_to_pixbuf().
Support for splitting the audio into blocks is not explicitly provided
and has to be done manually.

GdkPixbuf is useful as an intermediate step to producing PNG output.


AlphaBuf
--------

Alphabufs are useful in low level OpenGl applications.
They do not use much texture memory but are not as efficient
as using shaders.

eg to create a texture for use with Clutter:
```c
	Waveform* waveform = waveform_load_new("myfile.wav");
	AlphaBuf* a = waveform_alphabuf_new(waveform, -1, FALSE);
	texture = cogl_texture_new_from_data(a->width, a->height, COGL_TEXTURE_NONE, COGL_PIXEL_FORMAT_A_8, COGL_PIXEL_FORMAT_ANY, a->width, a->buf);
```

The above creates a texture for the whole file.
This is not appropriate for large files.

It is planned to add better support for Clutter in the near future.


Peak file cache
---------------

A cache of peak files is stored in XDG_CACHE_HOME (default ~/.cache/).
Files are removed if older than 30 days.
They are stored with standard WAV headers and contain alternating 16bit integer values for plus and minus peak values.
One pair of values (for each channel) is stored for every 256 frames of the original audio file.


Zoom levels
-----------

There are five distinct drawing modes depending on the zoom level.
Each mode has 16 times the resolution of the previous.

- Very Low res.
- Low res uses a 256 pixel texture per 256^3 audio frames.
- Std res uses a 256 pixel texture per 256^2 audio frames.
- Hi res draws individual lines, one per 16 audio frames.
- V Hi res draws at full resolution, ie using all audio frames.

