diff options
Diffstat (limited to 'doc/lv2_host_guide/lv2-host-perspective.adoc')
| -rw-r--r-- | doc/lv2_host_guide/lv2-host-perspective.adoc | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/doc/lv2_host_guide/lv2-host-perspective.adoc b/doc/lv2_host_guide/lv2-host-perspective.adoc new file mode 100644 index 0000000..c890c54 --- /dev/null +++ b/doc/lv2_host_guide/lv2-host-perspective.adoc @@ -0,0 +1,185 @@ +Introduction to LV2, a Plugin Host Perspective +============================================== +:toc: + +Intro +----- + +Hello there, if you're reading this document then you're likely trying to figure +out how to work with existing LV2 plugins and understanding some of the details +of the LV2 spec. +This document assumes some cursory knowledge about prior plugin standards +including LADSPA(link)/DSSI(link)/VST(link)/etc. +At the end of reading this guide you should be comfortable with setting up a +basic host which can process audio, MIDI, and control events using several of +the LV2 utility libraries in C. +If you're looking for a C++ implementation, we'll briefly explain how the +information within this guide can be translated at the end of this article. + +For the most part in this guide we'll refer to the official API specifications +for more clarifications, though several code examples will come from one of +several simple hosts including jalv(link) which is the reference implementation, +lv2file(link) (a simple wav file processor), lv2apply(), lv2ls(link), and ... + +What can LV2 plugins do? +------------------------ + +talk about the raw basics of audio synthesis, audio effects, midi effects, and +GUIs. +Have a brief mention of extensions, but do *NOT* talk about them until later. + +Perhaps mention the existance of .ttl files here and say xxx is abstracted away +by yyy. + + +The LV2 Ecosystem +----------------- + +If you're searching around for libraries related to LV2 you may come across a +wide variety of them. +This can include lilv(links), raul(for), suil(every), serd(one), sord(of the), +LV2 toolkit(libraries), and a few others. +Fortunately building a basic host is not that difficult and will primarily build +off of lilv. + +Talk about the other components as need be + +How can you load a LV2 plugin? +------------------------------ + +So, now that we know that we're using lilv, how can we load a simple plugin. +For this let's try to load one of the basic sample plugins 'eg-amp'. +Plugins within LV2 are loaded based upon URIs, so in the case of the 'eg-amp' +plugin LV2 names it 'http://lv2plug.in/plugins/eg-amp'. +(perhaps a brief footnote on why this is the case, but nothing more) + +First let's verify that this plugin is installed on your system + +-------------------------------------------------------------------------------- +void list_plugins(void) +{ + LilvWorld *world = lilv_world_new(); + lilv_world_load_all(world); + const LilvPlugins *plugins=lilv_world_get_all_plugins(lilvworld); + + LilvIter *plug_itr = lilv_plugins_begin(plugins); + for(int i=0; i<lilv_plugins_size(plugins); ++i) { + LilvPlugin *plugin = lilv_plugins_get(plugins, plug_itr); + LilvNode *uri_node = lilv_plugin_get_uri(plugin); + const char *uri_str = lilv_node_as_uri(uri_node); + printf("plugin.uri = %s\n", uri_str); + plug_itr = lilv_plugins_next(plugins, plug_itr); + } + + some_teardown_code_that_I_didn_t_bother_to_implement(); +} + +int main() +{ + list_plugins(); +} +-------------------------------------------------------------------------------- + +You can compile this snippet via XXX. +If you need some help getting the dependencies setup then please see appendix A +(this appendix should describe setup steps for the popular dev distros which at +the moment are (IMO) Ubuntu & Arch). +This code will open the lilv library and iterate through all the plugins +available to the LV2 host. +As long as you can see 'http://lv2plug.in/plugins/eg-amp' in the output, then +we're all ready to go to the next step, putting a few samples into the plugin. + + +-------------------------------------------------------------------------------- +LilvPlugin *get_the_plugin(void) {} + +xxx *create_plugin_instance(plugin, ...) {} + +//Activate instance + +//instance run + +//Cleanup + +-------------------------------------------------------------------------------- + +At this point we've created a plugin instance, activated it, and run it, but +how do we send data to it and get the results? + +That brings us to the concept of LV2 ports. + +- Input +- Output +- Audio +- Control (we'll get to this later) +- Etc (we'll get to this later) + +-------------------------------------------------------------------------------- +void connect_input_output_buffer() {...} +-------------------------------------------------------------------------------- + +With this connection in place we can connect the input an output data from the +host: + +-------------------------------------------------------------------------------- +//feed in dummy data before processing + +//read out the same dummy data (assuming that eg-amp defaults to unison gain) +-------------------------------------------------------------------------------- + +Great, we now have a plugin running and processing data within our trivial host + + +How do you control a LV2 plugin? +-------------------------------- + +This brings us to how you can interact with control ports, ... + + +LV2 Extensions +-------------- + +The core of LV2 does A, B, & C, but by design the specification makes it +possible for hosts to implement extensions that the plugins can make use of. +A common one is X. +Let's walk through the implementation of this extension and what happens when +plugin hosts have the functionality and when they do not have it. +For this example we're going to use the X plugin which you can download from +http://... + +Where to go from here? +---------------------- + +At this point in the guide you should have a rough idea as to what components +are needed for a LV2 host and how to assemble them. +There's still plenty more that can be done with LV2 and knowing about the +available resources can make this a much easier process. + +- http://lv2plug.in/api_spec_url +- http://the_link_to_liblilv + +Example hosts: + +- jalv - recommended for learning a,b,c +- lv2file - largely discussed within this guide +- ardour - see link to small part of the git repo to understand how X is used in + a large host as well as A,B,C to understand a few extensions + +Other interesting projects: + + +- LV2 mailing list +- LV2 IRC chat +- etc + + + +Appendix A: LV2 dependency setup +-------------------------------- + +Apt get yada yada +Compiler tweak abc, + +pacman xxx + + |