Libwaveform aims to provide efficient, versatile and easy-to-use display of audio waveforms for Gtk+-2 applications.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
agl
decoder
gtkglext-1.0
m4
package/gentoo/media-libs/libwaveform
sdl
shaders
test
transition
waveform
.gitignore
AUTHORS
ChangeLog
Makefile.am
NEWS
README
README.md
TODO
autogen.sh
configure.ac
libwaveform.pc.in

README.md

Overview

Libwaveform attempts to provide versatile easy-to-use interactive display of audio waveforms for Gtk+-2 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:

	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:

	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:

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