Finish up the documentation on the sampler.
[composite:composite.git] / data / doc / composite_sampler.docbook
1 <?xml version="1.0" encoding="UTF-8"?> <!-- -*- mode:nxml; indent-tabs-mode:nil; fill-column:80; -*- -->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.0//EN"
3                           "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
4 <refentry id="man.1.composite_sampler" lang="en">
5
6   <refentryinfo>
7     <productname>Composite</productname>
8     <author>
9       <firstname>Gabriel</firstname>
10       <othername>M.</othername>
11       <surname>Beddingfield</surname>
12       <authorblurb>
13         <para>&lt;gabriel@teuton.org&gt;</para>
14       </authorblurb>
15     </author>
16   </refentryinfo>
17
18   <refmeta>
19     <refentrytitle>composite_sampler</refentrytitle>
20     <manvolnum>1</manvolnum>
21     <refmiscinfo class='manual'>Audio Plugins</refmiscinfo>
22   </refmeta>
23
24   <refnamediv>
25     <refname>composite_sampler</refname>
26     <refpurpose>audio sampler/synth plugin (LV2)</refpurpose>
27   </refnamediv>
28
29   <refsect1>
30     <title>Description</title>
31
32     <para>The Composite sampler is an audio plugin (LV2) that provides a simple
33     sampling engine.  It is identified by the URI
34     <quote>http://gabe.is-a-geek.org/composite/plugins/sampler/1</quote></para>
35   </refsect1>
36
37   <refsect1>
38     <title>Ports</title>
39
40     <para>The sampler includes the following ports:</para>
41
42     <informaltable>
43       <tgroup cols='5' colsep='1' rowsep='1'>
44         <colspec colname='c0'/>
45         <colspec colname='c1'/>
46         <colspec colname='c2'/>
47         <colspec colname='c3'/>
48         <colspec colname='c4'/>
49         <thead>
50           <row>
51             <entry>Name</entry>
52             <entry>LV2 Port</entry>
53             <entry>Type</entry>
54             <entry>Flow</entry>
55             <entry>Description</entry>
56           </row>
57         </thead>
58         <tbody>
59           <row>
60             <entry>Left</entry>
61             <entry>out_left</entry>
62             <entry>AudioPort</entry>
63             <entry>Output</entry>
64             <entry>Left stereo channel output</entry>
65           </row>
66           <row>
67             <entry>Right</entry>
68             <entry>out_right</entry>
69             <entry>AudioPort</entry>
70             <entry>Output</entry>
71             <entry>Right stereo channel output</entry>
72           </row>
73           <row>
74             <entry>MIDI</entry>
75             <entry>midi</entry>
76             <entry>EventPort</entry>
77             <entry>Input</entry>
78             <entry>Main MIDI Input</entry>
79           </row>
80           <row>
81             <entry>Volume</entry>
82             <entry>volume</entry>
83             <entry>ControlPort</entry>
84             <entry>Input</entry>
85             <entry>Master volume [0.0-1.0]</entry>
86           </row>
87         </tbody>
88       </tgroup>
89     </informaltable>
90   </refsect1>
91
92   <refsect1>
93     <title>Controlling the Sampler</title>
94
95     <para>The primary way to control the sampler is over MIDI.  See
96     composite_midi(7) for complete documentation on the MIDI
97     implementation.</para>
98   </refsect1>
99
100   <refsect1>
101     <title>Drumkits</title>
102
103     <para>The drumkits for Composite are the same as for Hydrogen.  To reuse
104     your Hydrogen drumkits, copy or symlink them to
105     $HOME/.composite/data/drumkits/.  You can create and edit drumkits with
106     composite-gui (or Hydrogen).</para>
107
108   </refsect1>
109
110   <refsect1>
111     <title>Presets</title>
112
113     <para>The sampler responds to MIDI Program Change events.  Based on the
114     event that it receives, it will load up another file (e.g. a drumkit).  This
115     is how you can select the drumkit that you wish to use.</para>
116
117     <para>The presets are defined in a file
118     <filename>$HOME/.composite/data/presets/default.xml</filename>.  For the
119     sampler plugin, you can override this by using default-presets.xml, but at
120     the current time there is no need to.  When you first load the sampler, it
121     will check for this file.  If it doesn't exist, it will create one based on
122     all your user drumkits.</para>
123
124     <para>The presets file is a simple XML file that allows you to define MIDI
125     banks, and assign different resources for each program change.  An example
126     file is as follows:</para>
127
128     <programlisting><![CDATA[<?xml version="1.0"?>
129 <T:tritium xmlns:T="http://gabe.is-a-geek.org/tritium/xml/1/">
130     <T:presets>
131         <T:bank coarse="0" fine="0">
132             <T:program>
133                 <T:midi_number>0</T:midi_number>
134                 <T:resource>tritium:drumkits/GMkit</T:resource>
135             </T:program>
136             <T:program>
137                 <T:midi_number>1</T:midi_number>
138                 <T:resource>tritium:drumkits/TR808EmulationKit</T:resource>
139             </T:program>
140         </T:bank>
141     </T:presets>
142 </T:tritium>]]></programlisting>
143
144     <para>You can define several &lt;bank> elements for the MIDI banks.  The
145     attributes <varname>coarse</varname> and <varname>fine</varname> correspond
146     to the MIDI CC's 0 and 32.  Each &lt;program> section is a preset.  The
147     &lt;midi_number> corresponds to the number in the PC message.</para>
148
149     <para>The &lt;resource> element holds a URI/URL to the thing you want
150     loaded.  This will typically be a drum kit, but can be any kind of file that
151     Composite supports (like a .h2song, .h2pattern, etc.  The URL's supported
152     are file://, tritium:, and file names.</para>
153
154     <para>The tritium: scheme is designed to create portable URL's to things
155     like drum kits.  For example, the URL <quote>tritium:drumkits/GMkit</quote>
156     will load the drumkit <quote>GMkit</quote>, whether it's installed in the
157     user directory
158     (<filename>$HOME/.composite/data/drumkits/GMkit/drumkit.xml</filename>) or
159     in the system directory
160     (<filename>/usr/share/composite/data/drumkits/GMkit/drumkit.xml</filename>).</para>
161
162     <note><para>The XML namespace declaration
163     <quote>http://gabe.is-a-geek.org/tritium/xml/1/</quote> is not
164     optional.</para></note>
165
166   </refsect1>
167   
168   <refsect1>
169     <title>LV2 Extensions</title>
170
171     <para>This plugin uses the following extensions, and they must be supported
172     by any program (host) that wishes to use this plugin.  If the host does not
173     support them, the plugin will fail to load.</para>
174
175     <itemizedlist>
176       <listitem>
177         <para>Events &lt;http://lv2plug.in/ns/ext/event#&gt;</para>
178       </listitem>
179       <listitem>
180         <para>Midi Events &lt;http://lv2plug.in/ns/ext/midi#MidiEvent&gt;</para>
181       </listitem>
182     </itemizedlist>
183
184   </refsect1>
185
186   <refsect1>
187     <title>Files</title>
188
189     <para><emphasis>/usr/share/composite/data/</emphasis> &mdash; This is the
190     main folder where system data (drumkits, presets, etc.) are stored for
191     Composite and Composite Sampler.</para>
192
193     <para><emphasis>$HOME/.composite/data/</emphasis> &mdash; This is the main
194     folder where user data (drumkits, presets, etc.) are stored for Composite
195     and Composite Sampler.</para>
196
197     <para><emphasis>$HOME/.composite/data/drumkits/</emphasis> &mdash; This is
198     the main folder where user drumkits are stored.  Each drumkit has its own
199     folder, and each folder has a file 'drumkit.xml' that describes the
200     drumkit.</para>
201
202     <para><emphasis>$HOME/.composite/data/presets/default.xml</emphasis> &mdash;
203     This is the default presets file for Composite.  If it does not exist, it
204     will be created automatically using all of your installed drumkits.</para>
205
206
207     <para><emphasis>$HOME/.composite/data/presets/default.xml</emphasis> &mdash;
208     This is the default presets file for Composite.  If it does not exist, it
209     will be created automatically using all of your installed drumkits.</para>
210
211     <para><emphasis>$HOME/.composite/data/presets/default-plugin.xml</emphasis>
212     &mdash; This is the default presets file for the Composite Sampler.  If it
213     does not exist, then $HOME/.composite/data/presets/default.xml is
214     used.</para>
215
216   </refsect1>
217   <refsect1>
218     <title>See Also</title>
219
220     <para>composite_midi(7), lv2_jack_host(1)</para>
221   </refsect1>
222 </refentry>