Commits

Albert Graef  committed 72c0472

Update documentation.

  • Participants
  • Parent commits 0f5efa0

Comments (0)

Files changed (1)

File pure-lilv/README

 
 Albert Gräf <aggraef@gmail.com>
 
+Copying
+=======
+
+pure-lilv is Copyright (c) 2014 by Albert Gräf. It is distributed under a
+3-clause BSD license, please check the COPYING file included in the
+distribution for details.
+
+Installation
+============
+
+Get the latest source from
+https://bitbucket.org/purelang/pure-lang/downloads/pure-lilv-@version@.tar.gz.
+
+Run ``make`` to compile the module and ``sudo make install`` to install it in
+the Pure library directory. To uninstall the module, use ``sudo make
+uninstall``. There are a number of other targets (mostly for maintainers),
+please see the Makefile for details.
+
+``make`` tries to guess your Pure installation directory and platform-specific
+setup. If it gets this wrong, you can set some variables manually. In
+particular, ``make install prefix=/usr`` sets the installation prefix.
+
+Description
+===========
+
 This package provides a Pure module for David Robillard's Lilv_, a library for
 LV2 plugin host writers. LV2_ is the new Linux audio plugin standard (LADSPA
 successor) which aims to be portable and extensible. Lilv makes it possible to
 .. _Lilv: http://drobilla.net/software/lilv/
 .. _LV2: http://lv2plug.in/
 
-This module is still under development. When it is finished, it should provide
-all the common facilities needed to write LV2 hosts in Pure. We already offer
-operations to retrieve information about the LV2 plugins installed on a
-system, and to instantiate and run most basic plugins. Basic MIDI support is
-also available. More work is still needed in order to support more exotic
-event types such as transport state and tempo changes, handling of presets and
-plugin state, and any other extensions which may be required to run more
+This module is still under development, but we already offer operations to
+retrieve information about the LV2 plugins installed on a system, and to
+instantiate and run most basic plugins. Support for MIDI input and output and
+handling LV2 presets and plugin state is also available. More work is still
+needed in order to support more exotic event types such as transport state and
+tempo changes, and any other extensions which may be required to run more
 advanced plugins. We're still trying to figure these out, so if you notice
 anything that's missing in the current implementation then please submit a
 feature request.
 Documentation still needs to be written. For the time being, please refer to
 the lilv.pure script for a description of the programming interface, and to
 the scripts in the examples folder for examples showing how to use the
-operations provided by this module.
+operations provided by this module. Specifically, have a look at the
+lilv_examp.pure script which illustrates most the API functions and how they
+are used in a Pure script. There's also a fairly complete software synthesizer
+example, synth.pure, which shows how to run instrument and effect plugins in a
+synth/effects chain in order to synthesize audio from MIDI input.
 
-Copying
-=======
+Here's a brief excerpt from lilv_examp.pure which shows the necessary steps
+involved in running an LV2 audio plugin with Pure::
 
-pure-lilv is Copyright (c) 2014 by Albert Gräf. It is distributed under a
-3-clause BSD license, please check the COPYING file included in the
-distribution for details.
+  // Import the module.
+  using lilv;
+  // Load the LV2 world state.
+  let world = lilv::world;
+
+  // Instantiate a plugin.
+  let p = lilv::plugin world "http://faust-lv2.googlecode.com/amp" 44100 64;
+
+  // Get some information about the plugin (number of audio inputs and
+  // outputs, port descriptions).
+  let n,m = lilv::num_audio_inputs p, lilv::num_audio_outputs p;
+  let ports = [i, lilv::port_info p i | i = 0..lilv::num_ports p-1];
+
+  // Create some audio buffers for input and output.
+  let in = dmatrix {0,1,0,-1,0,1,-1,0;0,1,0,-1,0,1,-1,0};
+  let out = dmatrix (2,8);
+
+  // Activate the plugin.
+  lilv::activate p;
+
+  // Run some samples through the plugin.
+  lilv::run p in out;
+
+  // Set a control value.
+  lilv::set_control p 2 10;
+  // Compute some more samples.
+  lilv::run p in out;
+  // Get the values of some output controls.
+  map (lilv::get_control p) [4,5];
+
+  // Send a MIDI message.
+  lilv::set_midi p 10 [{0xb0, 7, 127}];
+  // Compute some more samples.
+  lilv::run p in out;
+
+.. Enjoy!