eq4 / libwaveform

Libwaveform aims to provide efficient, versatile and easy-to-use display of audio waveforms for Gtk+-2 applications.

Overview

Libwaveform attempts to provide versatile easy-to-use display of audio waveforms for Gtk+-2 applications.

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.
• 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 GtkGLExt using the WaveformActor interface
3. rendering to a GdkPixbuf
4. rendering to an Alphabuf

Requirements:

• Gtk2
• GtkGLExt
• Libsndfile
• 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.

Testing: Has been fully tested with Gallium 0.4 on Radeon RV530, RV620 and Cedar, and Intel 945 and HD3000. Radeon HD 5000 has issues at very hi res which look like driver bugs though this is not confirmed. Nvidia 8400 has been found to mostly work (Nouveau), though some issues are being investigated. 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:

	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 WfCanvas object. The canvas has the following directly settable properties:

	uint32_t sample_rate

In order to remain versatile, the WfCanvas is very minimal. For example it has no concept of time or tempo (positions are specified in x y coordinates).

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:

	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:

	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 four distinct drawing modes depending on the zoom level. Each mode has 16 times the resolution of the previous.

• 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.