-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathindex.html
More file actions
858 lines (856 loc) · 106 KB
/
index.html
File metadata and controls
858 lines (856 loc) · 106 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libfluidsynth: FluidSynth 1.1 Developer Documentation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">libfluidsynth
 <span id="projectnumber">1.1.11</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">FluidSynth 1.1 Developer Documentation </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><dl class="section author"><dt>Author</dt><dd>Peter Hanappe </dd>
<dd>
Conrad Berhörster </dd>
<dd>
Antoine Schmitt </dd>
<dd>
Pedro López-Cabanillas </dd>
<dd>
Josh Green </dd>
<dd>
David Henningsson </dd>
<dd>
Tom Moebert </dd>
<dd>
Copyright © 2003-2018 Peter Hanappe, Conrad Berhörster, Antoine Schmitt, Pedro López-Cabanillas, Josh Green, David Henningsson, Tom Moebert </dd></dl>
<dl class="section version"><dt>Version</dt><dd>Revision 1.1.11 </dd></dl>
<dl class="section date"><dt>Date</dt><dd>2018-05-04</dd></dl>
<p>All the source code examples in this document are in the public domain; you can use them as you please. This document is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License. To view a copy of this license, visit <a href="http://creativecommons.org/licenses/by-sa/3.0/">http://creativecommons.org/licenses/by-sa/3.0/</a> . The FluidSynth library is distributed under the GNU Lesser General Public License. A copy of the GNU Lesser General Public License is contained in the FluidSynth package; if not, visit <a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt">http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt</a> or write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.</p>
<h1><a class="anchor" id="Abstract"></a>
Abstract</h1>
<p><a href="http://www.fluidsynth.org">FluidSynth</a> is a software synthesizer based on the <a href="http://en.wikipedia.org/wiki/SoundFont">SoundFont 2</a> specifications. The synthesizer is available as a shared object that can easily be reused in any application that wants to use wave-table synthesis. This document explains the basic usage of FluidSynth. Some of the more advanced features are not yet discussed but will be added in future versions.</p>
<h1><a class="anchor" id="Contents"></a>
Table of Contents</h1>
<ul>
<li><a class="el" href="index.html#Disclaimer">Disclaimer</a></li>
<li><a class="el" href="index.html#Introduction">Introduction</a></li>
<li><a class="el" href="index.html#NewIn1_1_10">Whats new in 1.1.10?</a></li>
<li><a class="el" href="index.html#NewIn1_1_9">Whats new in 1.1.9?</a></li>
<li><a class="el" href="index.html#NewIn1_1_8">Whats new in 1.1.8?</a></li>
<li><a class="el" href="index.html#NewIn1_1_7">Whats new in 1.1.7?</a></li>
<li><a class="el" href="index.html#NewIn1_1_6">Whats new in 1.1.6?</a></li>
<li><a class="el" href="index.html#NewIn1_1_5">Whats new in 1.1.5?</a></li>
<li><a class="el" href="index.html#NewIn1_1_4">Whats new in 1.1.4?</a></li>
<li><a class="el" href="index.html#NewIn1_1_3">Whats new in 1.1.3?</a></li>
<li><a class="el" href="index.html#NewIn1_1_2">Whats new in 1.1.2?</a></li>
<li><a class="el" href="index.html#NewIn1_1_1">Whats new in 1.1.1?</a></li>
<li><a class="el" href="index.html#NewIn1_1_0">Whats new in 1.1.0?</a></li>
<li><a class="el" href="index.html#CreatingSettings">Creating and changing the settings</a></li>
<li><a class="el" href="index.html#CreatingSynth">Creating the synthesizer</a></li>
<li><a class="el" href="index.html#CreatingAudioDriver">Creating the Audio Driver</a></li>
<li><a class="el" href="index.html#UsingSynth">Using the synthesizer without an audio driver</a></li>
<li><a class="el" href="index.html#LoadingSoundfonts">Loading and managing SoundFonts</a></li>
<li><a class="el" href="index.html#SendingMIDI">Sending MIDI Events</a></li>
<li><a class="el" href="index.html#RealtimeMIDI">Creating a Real-time MIDI Driver</a></li>
<li><a class="el" href="index.html#MIDIPlayer">Loading and Playing a MIDI file</a></li>
<li><a class="el" href="index.html#FileRenderer">Fast file renderer for non-realtime MIDI file rendering</a></li>
<li><a class="el" href="index.html#MIDIPlayerMem">Playing a MIDI file from memory</a></li>
<li><a class="el" href="index.html#MIDIRouter">Real-time MIDI router</a></li>
<li><a class="el" href="index.html#Sequencer">Sequencer</a></li>
<li><a class="el" href="index.html#Shell">Shell interface</a></li>
<li><a class="el" href="index.html#Advanced">Advanced features, not yet documented. API reference may contain more info.</a></li>
</ul>
<h1><a class="anchor" id="Disclaimer"></a>
Disclaimer</h1>
<p>This documentation, in its current version, is incomplete. As always, the source code is the final reference.</p>
<p>SoundFont(R) is a registered trademark of E-mu Systems, Inc.</p>
<h1><a class="anchor" id="Introduction"></a>
Introduction</h1>
<p>What is FluidSynth?</p>
<ul>
<li>FluidSynth is a software synthesizer based on the SoundFont 2 specifications. The synthesizer is available as a shared object (a concept also named Dynamic Linking Library, or DLL) that can be easily reused in any application for wave-table synthesis. This document explains the basic usage of FluidSynth.</li>
<li>FluidSynth provides a Command Line Interface program ready to be used from the console terminal, offering most of the library functionalities to end users, among them the ability of render and play Standard MIDI Files, receive real-time MIDI events from external hardware ports and other applications, perform advanced routing of such events, enabling at the same time a local shell as well as a remote server commands interface.</li>
<li>FluidSynth is an API (Application Programming Interface) relieving programmers from a lot of details of reading SoundFont and MIDI events and files, and sending the digital audio output to a Sound Card. These tasks can be accomplished using a small set of functions. This document explains most of the API functions and gives short examples about them.</li>
<li>FluidSynth uses instrument samples contained in standard SF2 (SoundFont 2) files, having a file structure based on the RIFF format. The specification can be obtained here: <a href="http://connect.creativelabs.com/developer/SoundFont/Forms/AllItems.aspx">http://connect.creativelabs.com/developer/SoundFont/Forms/AllItems.aspx</a> but most users don't need to know any details of the format.</li>
<li>FluidSynth can easily be embedded in an application. It has a main header file, fluidsynth.h, and one dynamically linkable library. FluidSynth runs on Linux, Mac OS X, and the Windows platforms, and support for OS/2 and OpenSolaris is experimental. It has audio and midi drivers for all mentioned platforms but you can use it with your own drivers if your application already handles MIDI and audio input/output. This document explains the basic usage of FluidSynth and provides examples that you can reuse.</li>
<li>FluidSynth is open source, in active development. For more details, take a look at <a href="http://www.fluidsynth.org">http://www.fluidsynth.org</a></li>
</ul>
<h1><a class="anchor" id="NewIn1_1_10"></a>
Whats new in 1.1.10?</h1>
<p>Changes in FluidSynth 1.1.10 concerning developers:</p>
<ul>
<li><a class="el" href="misc_8h.html#a09b28945cdc794f1f9b5c8edb34fcd6e" title="Check if a file is a SoundFont file. ">fluid_is_soundfont()</a> checks for "sfbk" header</li>
<li>For a full list of bug fixes, see <a href="https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-1110">https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-1110</a></li>
</ul>
<h1><a class="anchor" id="NewIn1_1_9"></a>
Whats new in 1.1.9?</h1>
<p>Changes in FluidSynth 1.1.9 concerning developers:</p>
<ul>
<li>add a function for registering audio drivers based on acutal needs: <a class="el" href="audio_8h.html#ad35f9fb8b124e8e9e8829fa9efefeb34" title="Registers audio drivers to use. ">fluid_audio_driver_register()</a></li>
<li>dsound driver now uses the desktop window handle, fluid_get_hinstance() and fluid_set_hinstance() are deprecated</li>
<li>implement handling of <a class="el" href="event_8h.html#a98ada1fab7a3785a41aa4003645640ebac1594ded0babd5412fc714d017dd7a76" title="All sounds off event. ">FLUID_SEQ_ALLSOUNDSOFF</a> events in fluid_seq_fluidsynth_callback()</li>
<li>fix return value of <a class="el" href="audio_8h.html#a9915ff06a55cc1fa52fe6eb079cb8718" title="Set vbr encoding quality (only available with libsndfile support) ">fluid_file_set_encoding_quality()</a></li>
<li>deprecate <a class="el" href="synth_8h.html#a473592b54847c90e359fa8c18edbc87d" title="Set a SoundFont generator (effect) value on a MIDI channel in real-time. ">fluid_synth_set_gen2()</a></li>
<li>For a full list of bug fixes, see <a href="https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-119">https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-119</a></li>
</ul>
<h1><a class="anchor" id="NewIn1_1_8"></a>
Whats new in 1.1.8?</h1>
<p>Changes in FluidSynth 1.1.8 concerning developers:</p>
<ul>
<li><a class="el" href="synth_8h.html#a3fba596ce8f5f4c0e54d8013348e80c4" title="Get active preset on a MIDI channel. ">fluid_synth_get_channel_preset()</a> is not deprecated anymore</li>
<li>deprecate <a class="el" href="synth_8h.html#a80f40cdecd1db919d2a0ba80f10907e6" title="Get information on the currently selected preset on a MIDI channel. ">fluid_synth_get_channel_info()</a></li>
<li>deprecate <a class="el" href="synth_8h.html#a19e0147dddbfbd54a5c13c140c95608d" title="Assign a MIDI router to a synth. ">fluid_synth_set_midi_router()</a></li>
<li>deprecate redundant tuning functions</li>
<li>deprecate <a class="el" href="gen_8h.html#aa15008d347132b989970e91cb142413b" title="Set an array of generators to their default values. ">fluid_gen_set_default_values()</a></li>
<li>deprecate struct <a class="el" href="struct__fluid__mod__t.html" title="Modulator structure. ">_fluid_mod_t</a>, use the respective getter and setter functions</li>
<li>For a full list of bug fixes, see <a href="https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-118">https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-118</a></li>
</ul>
<h1><a class="anchor" id="NewIn1_1_7"></a>
Whats new in 1.1.7?</h1>
<p>Changes in FluidSynth 1.1.7 concerning developers:</p>
<ul>
<li>"synth.parallel-render" has been deprecated</li>
<li><a class="el" href="synth_8h.html#a55af07ef3c725366ac8c77d1d3f032c9" title="Set midi channel type. ">fluid_synth_set_channel_type()</a> was not exported properly</li>
<li>"audio.jack.multi" had inverse logic</li>
<li>fluid_synth_write_*() had timing issues when requesting more than 64 audio frames</li>
<li>reverb and chorus are routed to distinct buffers in <a class="el" href="synth_8h.html#a2e394b30908133eed97fe903d5654bac" title="Synthesize a block of floating point audio to separate audio buffers (multichannel rendering)...">fluid_synth_nwrite_float()</a></li>
<li>vorbis-compressed sf3 sound fonts are supported</li>
<li>the following getters have been added: <a class="el" href="voice_8h.html#a2d1e2d91b210ca21af5b39e4c2e93e20" title="Check if a voice is ON. ">fluid_voice_is_on()</a>, <a class="el" href="voice_8h.html#ac5ebe017d7399cf1f3d4cf8b62cf0b00" title="Check if a voice keeps playing after it has received a noteoff due to being held by sustain...">fluid_voice_is_sustained()</a>, <a class="el" href="voice_8h.html#af5380a5512639e6611ae7b2076909bb4" title="Check if a voice keeps playing after it has received a noteoff due to being held by sostenuto...">fluid_voice_is_sostenuto()</a>, <a class="el" href="voice_8h.html#a2794e73013c6d785a7f912972a1798b5" title="If the voice is playing, gets the midi channel the voice is playing on. ">fluid_voice_get_channel()</a>, <a class="el" href="voice_8h.html#ad3ad3749dadea3c31beec5e3614ca51b" title="If the voice is playing, gets the midi key from the noteon event, by which the voice was initially tu...">fluid_voice_get_key()</a>, <a class="el" href="voice_8h.html#a318a4e5aac732628b28cbafffb936643" title="If the voice is playing, gets the midi key the voice is actually playing at. ">fluid_voice_get_actual_key()</a>, <a class="el" href="voice_8h.html#aa379f6edf2dedc391a276c7571a5c1cc" title="If the voice is playing, gets the midi velocity from the noteon event, by which the voice was initial...">fluid_voice_get_velocity()</a>, <a class="el" href="voice_8h.html#a14b60445ee2d7a7b21b01dbfdeb51356" title="If the voice is playing, gets the midi velocity the voice is actually playing at. ...">fluid_voice_get_actual_velocity()</a>, <a class="el" href="midi_8h.html#a74798d9e7fa9d8f7ed0ce0830a39f344" title="Get the number of tempo ticks passed. ">fluid_player_get_current_tick()</a>, <a class="el" href="midi_8h.html#a68decb1f632bfd1c7106ed77eb63e453" title="Looks through all available MIDI tracks and gets the absolute tick of the very last event to play...">fluid_player_get_total_ticks()</a>, <a class="el" href="midi_8h.html#a5877f176c3d7378fd2088ce5ef0f6e70" title="Get the tempo of a MIDI player in beats per minute. ">fluid_player_get_bpm()</a>, <a class="el" href="midi_8h.html#a36152179a7b28d962038a39f8fd59a12" title="Get the tempo of a MIDI player. ">fluid_player_get_midi_tempo()</a></li>
<li>the following enum values have been deprecated: <code>FLUID_SEQ_LASTEVENT</code>, <code>GEN_LAST</code>, <code>LAST_LOG_LEVEL</code> </li>
<li>For a full list of bug fixes, see <a href="https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-117">https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-117</a></li>
</ul>
<h1><a class="anchor" id="NewIn1_1_6"></a>
Whats new in 1.1.6?</h1>
<p>Changes in FluidSynth 1.1.6 concerning developers:</p>
<ul>
<li>The player will not continue to the next song until all EOT (end of track events) have been reached.</li>
<li>Enable long arguments on all platforms where getopt.h is available</li>
<li>Windows: Fluidsynth.pc (pkg-config spec) is now installed.</li>
<li>Mac OS X Lion: A build failure was fixed.</li>
<li>For a full list of bug fixes, see <a href="https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-116">https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-116</a></li>
</ul>
<h1><a class="anchor" id="NewIn1_1_5"></a>
Whats new in 1.1.5?</h1>
<p>Changes in FluidSynth 1.1.5 concerning developers:</p><ul>
<li>A change in the Jack driver might require a newer Jack version compared to 1.1.4.</li>
<li>For a full list of bug fixes, see <a href="https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-115">https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-115</a></li>
</ul>
<h1><a class="anchor" id="NewIn1_1_4"></a>
Whats new in 1.1.4?</h1>
<p>Changes in FluidSynth 1.1.4 concerning developers:</p>
<ul>
<li>You can now play MIDI files that reside in memory (instead of specifying a filename). See <a class="el" href="index.html#MIDIPlayerMem">Playing a MIDI file from memory</a> for an example.</li>
<li>A hook can be inserted for MIDI file playback, at playback time. This is done through the new fluid_player_set_playback_callback API function. You can use this to both inspect and modify MIDI events as they are being played (or add a MIDI router), just as you can for MIDI input drivers.</li>
<li>Channel 10 used to be the one and only drum channel, this can now be changed using the fluid_synth_set_channel_type.</li>
<li>fluid_synth_all_sounds_off and fluid_synth_all_notes_off are new public API functions. You can use them to turn notes off (i e releasing all keys, voices advance to release phase) or sounds off (more like pressing the mute button), for one channel or all channels.</li>
<li>For Mac OS X users: The CoreAudio driver has been adapted to use AuHAL, and the default build style has changed to "FluidSynth.framework".</li>
<li>For a full list of other enhancements and bug fixes, see <a href="https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-114">https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-114</a></li>
</ul>
<h1><a class="anchor" id="NewIn1_1_3"></a>
Whats new in 1.1.3?</h1>
<p>Changes in FluidSynth 1.1.3 concerning developers:</p>
<ul>
<li>There are no new API additions in 1.1.3, this is a pure bug-fix release. For a list of bugs fixed, see <a href="https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-113">https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-113</a></li>
</ul>
<h1><a class="anchor" id="NewIn1_1_2"></a>
Whats new in 1.1.2?</h1>
<p>Changes in FluidSynth 1.1.2 concerning developers:</p>
<ul>
<li>Build system has switched from autotools to CMake. For more information, see README.cmake. The autotools build system is still working, but it is deprecated. The "winbuild" and "macbuild" directories have been dropped in favor of CMake's ability to create project files on demand.</li>
<li>Thread safety has been reworked to overcome the limitations and bugs in version 1.1.0 and 1.1.1. There are two new settings controlling the thread safety, synth.threadsafe-api and synth.parallel-render. More information about these settings is in the <a class="el" href="index.html#CreatingSettings">Creating and changing the settings</a> section. Please look them through and set them appropriately according to your use case.</li>
<li>Voice overflow, i e what voice to kill when polyphony is exceeded, is now configurable.</li>
<li>Possibility to update polyphony and sample rate real-time. Note that updating polyphony is not hard real-time safe, and updating sample rate will kill all currently sounding voices.</li>
<li>MIDI Bank Select handling is now configurable. See the synth.midi-bank-select setting in the <a class="el" href="index.html#CreatingSettings">Creating and changing the settings</a> section for more information.</li>
<li>Can use RealTimeKit (on Linux) to get real-time priority, if the original attempt fails. Note that you'll need development headers for DBus to enable this functionality.</li>
<li>Shell commands for pitch bend and pitch bend range.</li>
<li>PulseAudio driver: two new settings allows you to specify media role, and control whether pulseaudio can adjust latency.</li>
</ul>
<h1><a class="anchor" id="NewIn1_1_1"></a>
Whats new in 1.1.1?</h1>
<p>Changes in FluidSynth 1.1.1 concerning developers:</p>
<ul>
<li><a class="el" href="synth_8h.html#a3fba596ce8f5f4c0e54d8013348e80c4" title="Get active preset on a MIDI channel. ">fluid_synth_get_channel_preset()</a> marked as deprecated. New function <a class="el" href="synth_8h.html#a80f40cdecd1db919d2a0ba80f10907e6" title="Get information on the currently selected preset on a MIDI channel. ">fluid_synth_get_channel_info()</a> added which is thread safe and should replace most uses of the older function.</li>
<li>Added <a class="el" href="synth_8h.html#a5541af149bb98e0eaaf91f5d3419cb10" title="Set the preset of a MIDI channel to an unassigned state. ">fluid_synth_unset_program()</a> to unset the active preset on a channel.</li>
</ul>
<h1><a class="anchor" id="NewIn1_1_0"></a>
Whats new in 1.1.0?</h1>
<p>Overview of changes in FluidSynth 1.1.0 concerning developers:</p>
<ul>
<li>Extensive work to make FluidSynth thread safe. Previous versions had many multi-thread issues which could lead to crashes or synthesis glitches. Some of the API additions, deprecations and function recommended conditions of use are related to this work.</li>
<li>File renderer object for rendering audio to files.</li>
<li>Sequencer objects can now use the system timer or the sample clock. When using the sample clock, events are triggered based on the current output audio sample position. This means that MIDI is synchronized with the audio and identical output will be achieved for the same MIDI event input.</li>
<li>libsndfile support for rendering audio to different formats and file types.</li>
<li>API for using the MIDI router subsystem.</li>
<li>MIDI Tuning Standard functions were added for specifying whether to activate tuning changes in realtime or not.</li>
<li>SYSEX support (MIDI Tuning Standard only at the moment).</li>
<li>Changed all yes/no boolean string settings to integer <a class="el" href="settings_8h.html#a3a8898f5a93139fbc35f5dfe39ed9f5a" title="Hint FLUID_HINT_TOGGLED indicates that the data item should be considered a Boolean toggle...">FLUID_HINT_TOGGLED</a> settings with backwards compatibility (assignment and query of boolean values as strings).</li>
<li>Many other improvements and bug fixes.</li>
</ul>
<p>API additions:</p>
<ul>
<li>A file renderer can be created with <a class="el" href="audio_8h.html#a9d9338a870c5f71ba6fad6db7d17a93e" title="Create a new file renderer and open the file. ">new_fluid_file_renderer()</a>, deleted with <a class="el" href="audio_8h.html#a6893d780de15030366e2399293ed7362" title="Close file and destroy a file renderer object. ">delete_fluid_file_renderer()</a> and a block of audio processed with <a class="el" href="audio_8h.html#abdea2fb753cf1a5fa9b5dca38c177d80" title="Write period_size samples to file. ">fluid_file_renderer_process_block()</a>.</li>
<li>Additional functions were added for using the MIDI router subsystem. To clear all rules from a router use <a class="el" href="midi_8h.html#a57aed5e84828c202452e13f265dd72f7" title="Clear all rules in a MIDI router. ">fluid_midi_router_clear_rules()</a> and to set a router to default rules use <a class="el" href="midi_8h.html#a32ecd2bdcc9bce39d0e0c68e5c1b80cb" title="Set a MIDI router to use default "unity" rules. ">fluid_midi_router_set_default_rules()</a>. To create a router rule use <a class="el" href="midi_8h.html#a128bc8b126cbabf7717149123815d235" title="Create a new MIDI router rule. ">new_fluid_midi_router_rule()</a> and to delete a rule use <a class="el" href="midi_8h.html#af1ba4e46f279d4d177169446d85bf06c" title="Free a MIDI router rule. ">delete_fluid_midi_router_rule()</a> (seldom used). Set values of a router rule with <a class="el" href="midi_8h.html#acc264709865c1e2dc972528cca55dc6f" title="Set the channel portion of a rule. ">fluid_midi_router_rule_set_chan()</a>, <a class="el" href="midi_8h.html#ac4f572c218943ded7fe43692a265ddb5" title="Set the first parameter portion of a rule. ">fluid_midi_router_rule_set_param1()</a> and <a class="el" href="midi_8h.html#a20afb0ffeb59c373534e5d46ed3d4b73" title="Set the second parameter portion of a rule. ">fluid_midi_router_rule_set_param2()</a>. <a class="el" href="midi_8h.html#aa1894a103cde4f1efe80c7c9d5096ae2" title="Add a rule to a MIDI router. ">fluid_midi_router_add_rule()</a> can be used to add a rule to a router.</li>
<li>New MIDI event functions were added, including <a class="el" href="event_8h.html#af6af8215438942a79dc953ba8419d1ac" title="Set a sequencer event to be a channel-wide aftertouch event. ">fluid_event_channel_pressure()</a>, <a class="el" href="event_8h.html#ae58c2c79f68a9e8d9ba70281013a9bcf" title="Set a sequencer event to be a midi system reset event. ">fluid_event_system_reset()</a>, and <a class="el" href="event_8h.html#a1af14ec5decbc1fcbdf1d5404f0c1bc6" title="Set a sequencer event to be an unregistering event. ">fluid_event_unregistering()</a>.</li>
<li>Additional sequencer functions include <a class="el" href="seqbind_8h.html#aecf29486fa3b80514be4a6a535b02045" title="Transforms an incoming midi event (from a midi driver or midi router) to a sequencer event and adds i...">fluid_sequencer_add_midi_event_to_buffer()</a>, <a class="el" href="seq_8h.html#a2ae3552fe3a4f20b8a29854c93eed643" title="Check if a sequencer is using the system timer or not. ">fluid_sequencer_get_use_system_timer()</a> and <a class="el" href="seq_8h.html#a3210e5a6b8a23c25038b91d0810a0a02" title="Advance a sequencer that isn't using the system timer. ">fluid_sequencer_process()</a>. <a class="el" href="seq_8h.html#a3c27499606024a92bca0b32dbcf72c44" title="Create a new sequencer object. ">new_fluid_sequencer2()</a> was added to allow for the timer type to be specified (system or sample clock).</li>
<li>The settings subsystem has some new functions for thread safety: <a class="el" href="settings_8h.html#ab77b24ccdb7d1eeb96f5933eb6099346" title="Copy the value of a string setting. ">fluid_settings_copystr()</a> and <a class="el" href="settings_8h.html#aa2cf8ed808a4ce5fcfdfb208ea77811b" title="Duplicate the value of a string setting. ">fluid_settings_dupstr()</a>. Also there are new convenience functions to count the number of string options for a setting: <a class="el" href="settings_8h.html#a2b0f4f5c31f722633b20e9f2aae45fcc" title="Count option string values for a string setting. ">fluid_settings_option_count()</a> and for concatenating setting options with a separator: <a class="el" href="settings_8h.html#a7c78d673d39c3463339612f7a508cda4" title="Concatenate options for a string setting together with a separator between. ">fluid_settings_option_concat()</a>.</li>
<li>MIDI Tuning Standard functions added include: <a class="el" href="synth_8h.html#a82eea41553b546ec063c2dc840ca711d" title="Set the tuning of the entire MIDI note scale. ">fluid_synth_activate_key_tuning()</a>, <a class="el" href="synth_8h.html#a50ffe674e0e4ae9c778cfe41eabf110b" title="Activate an octave tuning on every octave in the MIDI note scale. ">fluid_synth_activate_octave_tuning()</a>, <a class="el" href="synth_8h.html#ad370b81904a65188981c45ee840204d3" title="Activate a tuning scale on a MIDI channel. ">fluid_synth_activate_tuning()</a> and <a class="el" href="synth_8h.html#a7d3c0e7ce720c8f1b8a2de2f950d438f" title="Clear tuning scale on a MIDI channel (use default equal tempered scale). ">fluid_synth_deactivate_tuning()</a>. All of which provide a parameter for specifying if tuning changes should occur in realtime (affect existing voices) or not.</li>
<li>Additional synthesizer API: <a class="el" href="synth_8h.html#a5856acea557bb30b8c8cfbaf7bd008c6" title="Get SoundFont by name. ">fluid_synth_get_sfont_by_name()</a> to get a SoundFont by name, <a class="el" href="synth_8h.html#a38d8dc2f680024ce927f01424c13d32b" title="Select an instrument on a MIDI channel by SoundFont name, bank and program numbers. ">fluid_synth_program_select_by_sfont_name()</a> to select an instrument by SoundFont name/bank/program, <a class="el" href="synth_8h.html#a473592b54847c90e359fa8c18edbc87d" title="Set a SoundFont generator (effect) value on a MIDI channel in real-time. ">fluid_synth_set_gen2()</a> for specifying additional parameters when assigning a generator value, <a class="el" href="synth_8h.html#a28f34d0493b102ac4b99c021257b5b5e" title="Process a MIDI SYSEX (system exclusive) message. ">fluid_synth_sysex()</a> for sending SYSEX messages to the synth and <a class="el" href="synth_8h.html#a5d6f71e63f60df1a83e8490a867d8910" title="Get current number of active voices. ">fluid_synth_get_active_voice_count()</a> to get the current number of active synthesis voices.</li>
<li>Miscellaneous additions: <a class="el" href="midi_8h.html#af8343daaeb32ed1bd5bcc4c0be00c2fc" title="Enable looping of a MIDI player. ">fluid_player_set_loop()</a> to set playlist loop count and <a class="el" href="midi_8h.html#ad9b5bd5dcacaa1c967275f537e2add26" title="Get MIDI player status. ">fluid_player_get_status()</a> to get current player state.</li>
</ul>
<h1><a class="anchor" id="CreatingSettings"></a>
Creating and changing the settings</h1>
<p>Before you can use the synthesizer, you have to create a settings object. The settings objects is used by many components of the FluidSynth library. It gives a unified API to set the parameters of the audio drivers, the midi drivers, the synthesizer, and so forth. A number of default settings are defined by the current implementation.</p>
<p>All settings have a name that follows the "dotted-name" notation. For example, "synth.polyphony" refers to the number of voices (polyphony) preallocated by the synthesizer. The settings also have a type. There are currently three types: strings, numbers (double floats), and integers. You can change the values of a setting using the <a class="el" href="settings_8h.html#a855e6038c9946b206156eb1947746032" title="Set a string value for a named setting. ">fluid_settings_setstr()</a>, <a class="el" href="settings_8h.html#a2a31fd030256303d4076df5abdd603e7" title="Set a numeric value for a named setting. ">fluid_settings_setnum()</a>, and <a class="el" href="settings_8h.html#a26e4192ab084382492589f2c5d8b2e2f" title="Set an integer value for a setting. ">fluid_settings_setint()</a> functions. For example:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <fluidsynth.h></span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv) </div><div class="line">{</div><div class="line"> <a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba">fluid_settings_t</a>* settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949">new_fluid_settings</a>();</div><div class="line"> <a class="code" href="settings_8h.html#a26e4192ab084382492589f2c5d8b2e2f">fluid_settings_setint</a>(settings, <span class="stringliteral">"synth.polyphony"</span>, 128);</div><div class="line"> <span class="comment">/* ... */</span></div><div class="line"> <a class="code" href="settings_8h.html#a550270f09e4f3c645cbe9e6d3c514ca4">delete_fluid_settings</a>(settings);</div><div class="line"> <span class="keywordflow">return</span> 0;</div><div class="line">}</div></div><!-- fragment --><p>The API contains the functions to query the type, the current value, the default value, the range and the "hints" of a setting. The range is the minimum and maximum value of the setting. The hints gives additional information about a setting. For example, whether a string represents a filename. Or whether a number should be interpreted on on a logarithmic scale. Check the <a class="el" href="settings_8h.html" title="Synthesizer settings. ">settings.h</a> API documentation for a description of all functions.</p>
<h1><a class="anchor" id="CreatingSynth"></a>
Creating the synthesizer</h1>
<p>To create the synthesizer, you pass it the settings object, as in the following example:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <fluidsynth.h></span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv) </div><div class="line">{</div><div class="line"> <a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba">fluid_settings_t</a>* settings;</div><div class="line"> <a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4">fluid_synth_t</a>* synth;</div><div class="line"> settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949">new_fluid_settings</a>();</div><div class="line"> synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178">new_fluid_synth</a>(settings);</div><div class="line"></div><div class="line"> <span class="comment">/* Do useful things here */</span></div><div class="line"></div><div class="line"> <a class="code" href="synth_8h.html#a585a63f3a25b9df17b82ae87f2d38cfc">delete_fluid_synth</a>(synth);</div><div class="line"> <a class="code" href="settings_8h.html#a550270f09e4f3c645cbe9e6d3c514ca4">delete_fluid_settings</a>(settings);</div><div class="line"> <span class="keywordflow">return</span> 0;</div><div class="line">}</div></div><!-- fragment --><p>The following table provides details on all the settings used by the synthesizer.</p>
<a class="anchor" id=""></a>
<table border="1" cellspacing="0">
<caption>Table 1. Synthesizer settings</caption>
<tr>
<td>synth.audio-channels </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>1 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>1-128 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">By default, the synthesizer outputs a single stereo signal. Using this option, the synthesizer can output multichannel audio. Sets the number of stereo channel pairs. So 1 is actually 2 channels (a stereo pair). </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.audio-groups </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>1 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>1-128 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Normally the same value as synth.audio-channels. LADSPA effects subsystem can use this value though, in which case it may differ. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.chorus.active </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>1 (TRUE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">When set to 1 (TRUE) the chorus effects module is activated. Otherwise, no chorus will be added to the output signal. Note that the amount of signal sent to the chorus module depends on the "chorus send" generator defined in the SoundFont. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.cpu-cores </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>1 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>1-256 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">(Experimental) Sets the number of synthesis CPU cores. If set to a value greater than 1, then additional synthesis threads will be created to take advantage of a multi CPU or CPU core system. This has the affect of utilizing more of the total CPU for voices or decreasing render times when synthesizing audio to a file. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.device-id </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>0 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>0-126 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Device identifier used for SYSEX commands, such as MIDI Tuning Standard commands. Only those SYSEX commands destined for this ID or to all devices will be acted upon. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.dump </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>0 (FALSE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Does nothing currently. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.effects-channels </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>2 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>2-2 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd"></p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.gain </td><td>Type </td><td>number </td></tr>
<tr>
<td></td><td>Default </td><td>0.2 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>0.0-10.0 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The gain is applied to the final or master output of the synthesizer. It is set to a low value by default to avoid the saturation of the output when many notes are played. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.ladspa.active </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>0 (FALSE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">When set to "yes" the LADSPA subsystem will be enabled. This subsystem allows to load and interconnect LADSPA plug-ins. The output of the synthesizer is processed by the LADSPA subsystem. Note that the synthesizer has to be compiled with LADSPA support. More information about the LADSPA subsystem later. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.midi-channels </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>16 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>16-256 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">This setting defines the number of MIDI channels of the synthesizer. The MIDI standard defines 16 channels, so MIDI hardware is limited to this number. Internally FluidSynth can use more channels which can be mapped to different MIDI sources. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.midi-bank-select </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>gs </td></tr>
<tr>
<td></td><td>Options </td><td>gm, gs, xg, mma </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">This setting defines how the synthesizer interprets Bank Select messages. </p><ul>
<li>
gm: ignores CC0 and CC32 messages. </li>
<li>
gs: (default) CC0 becomes the bank number, CC32 is ignored. </li>
<li>
xg: CC32 becomes the bank number, CC0 is ignored. </li>
<li>
mma: bank is calculated as CC0*128+CC32. </li>
</ul>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.min-note-length </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>10 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>0-65535 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Sets the minimum note duration in milliseconds. This ensures that really short duration note events, such as percussion notes, have a better chance of sounding as intended. Set to 0 to disable this feature. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.parallel-render </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>1 (TRUE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">synth.parallel-render is the low-latency setting. If on, you're allowed to call fluid_synth_write_s16, fluid_synth_write_float, fluid_synth_nwrite_float or fluid_synth_process in parallel with the rest of the calls, and it won't be blocked by time intensive calls to the synth. Turn it off if throughput is more important than latency, e g in rendering-to-file scenarios where underruns is not an issue. <br />
<br />
<b>Deprecated:</b><br />
As of 1.1.7 this option is deprecated. This option enforces thread safety for rvoice_mixer, which causes rvoice_events to be queued internally. The current implementation relies on the fact that this option is set to TRUE to correctly render any amount of requested audio. Also calling fluid_synth_write_* in parallel is not considered to be a use-case. It would cause undefined audio output, as it would be unpredictable for the user which rvoice_events specifically would be dispatched to which fluid_synth_write_* call. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.polyphony </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>256 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>1-65535 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The polyphony defines how many voices can be played in parallel. A note event produces one or more voices. Its good to set this to a value which the system can handle and will thus limit FluidSynth's CPU usage. When FluidSynth runs out of voices it will begin terminating lower priority voices for new note events. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.reverb.active </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>1 (TRUE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">When set to 1 (TRUE) the reverb effects module is activated. Otherwise, no reverb will be added to the output signal. Note that the amount of signal sent to the reverb module depends on the "reverb send" generator defined in the SoundFont. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.sample-rate </td><td>Type </td><td>number </td></tr>
<tr>
<td></td><td>Default </td><td>44100 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>22050-96000 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The sample rate of the audio generated by the synthesizer. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.threadsafe-api </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>1 (TRUE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">synth.threadsafe-api controls whether the synth's public API is protected by a mutex or not. Default is on, turn it off for slightly better performance if you know you're only accessing the synth from one thread only, this could be the case in many embedded use cases for example. Note that libfluidsynth can use many threads by itself (shell is one, midi driver is one, midi player is one etc) so you should usually leave it on. Also see synth.parallel-render. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.verbose </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>0 (FALSE) </td></tr>
<tr>
<td></td><td>Description </td><td>When set to 1 (TRUE) the synthesizer will print out information about the received MIDI events to the stdout. This can be helpful for debugging. This setting cannot be changed after the synthesizer has started. </td></tr>
</table>
<h1><a class="anchor" id="CreatingAudioDriver"></a>
Creating the Audio Driver</h1>
<p>The synthesizer itself does not write any audio to the audio output. This allows application developers to manage the audio output themselves if they wish. The next section describes the use of the synthesizer without an audio driver in more detail.</p>
<p>Creating the audio driver is straightforward: set the appropriate settings and create the driver object. Because the FluidSynth has support for several audio systems, you may want to change which one you want to use. The list below shows the audio systems that are currently supported. It displays the name, as used by the fluidsynth library, and a description.</p>
<ul>
<li>jack: JACK Audio Connection Kit (Linux, Mac OS X, Windows)</li>
<li>alsa: Advanced Linux Sound Architecture (Linux)</li>
<li>oss: Open Sound System (Linux, Unix)</li>
<li>pulseaudio: PulseAudio (Linux, Mac OS X, Windows)</li>
<li>coreaudio: Apple CoreAudio (Mac OS X)</li>
<li>dsound: Microsoft DirectSound (Windows)</li>
<li>portaudio: PortAudio Library (Mac OS 9 & X, Windows, Linux)</li>
<li>sndman: Apple SoundManager (Mac OS Classic)</li>
<li>dart: DART sound driver (OS/2)</li>
<li>file: Driver to output audio to a file</li>
</ul>
<p>The default audio driver depends on the settings with which FluidSynth was compiled. You can get the default driver with <a class="el" href="settings_8h.html#a9cfe000758040d2115c071b47d0fb8a2" title="Get the default value of a string setting. ">fluid_settings_getstr_default()</a>. To get the list of available drivers use the <a class="el" href="settings_8h.html#aa9d54c924145af95e66a695230b8df71" title="Iterate the available options for a named string setting, calling the provided callback function for ...">fluid_settings_foreach_option()</a> function. Finally, you can set the driver with <a class="el" href="settings_8h.html#a855e6038c9946b206156eb1947746032" title="Set a string value for a named setting. ">fluid_settings_setstr()</a>. In most cases, the default driver should work out of the box.</p>
<p>Additional options that define the audio quality and latency are "audio.sample-format", "audio.period-size", and "audio.periods". The details are described later.</p>
<p>You create the audio driver with the <a class="el" href="audio_8h.html#a4ad51317b10b89bfe94ade5db345864b" title="Create a new audio driver. ">new_fluid_audio_driver()</a> function. This function takes the settings and synthesizer object as arguments. For example:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> init() </div><div class="line">{</div><div class="line"> <a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba">fluid_settings_t</a>* settings;</div><div class="line"> <a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4">fluid_synth_t</a>* synth;</div><div class="line"> <a class="code" href="types_8h.html#ac3706330ce49cac5b7dd079e90d376d8">fluid_audio_driver_t</a>* adriver;</div><div class="line"> settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949">new_fluid_settings</a>();</div><div class="line"></div><div class="line"> <span class="comment">/* Set the synthesizer settings, if necessary */</span></div><div class="line"> synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178">new_fluid_synth</a>(settings);</div><div class="line"></div><div class="line"> <a class="code" href="settings_8h.html#a855e6038c9946b206156eb1947746032">fluid_settings_setstr</a>(settings, <span class="stringliteral">"audio.driver"</span>, <span class="stringliteral">"jack"</span>);</div><div class="line"> adriver = <a class="code" href="audio_8h.html#a4ad51317b10b89bfe94ade5db345864b">new_fluid_audio_driver</a>(settings, synth);</div><div class="line">}</div></div><!-- fragment --><p>As soon as the audio driver is created, it will start playing. The audio driver creates a separate thread that uses the synthesizer object to generate the audio.</p>
<p>There are a number of general audio driver settings. The audio.driver settings define the audio subsystem that will be used. The audio.periods and audio.period-size settings define the latency and robustness against scheduling delays. There are additional settings for the audio subsystems used which are documented in another table.</p>
<a class="anchor" id=""></a>
<table border="1" cellspacing="0">
<caption>Table 2. General audio driver settings</caption>
<tr>
<td>audio.driver </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>jack (Linux), dsound (Windows), sndman (MacOS9), coreaudio (Mac OS X), dart (OS/2) </td></tr>
<tr>
<td></td><td>Options </td><td>jack, alsa, oss, pulseaudio, coreaudio, dsound, portaudio, sndman, dart, file </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The audio system to be used. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.periods </td><td>Type </td><td>int </td></tr>
<tr>
<td></td><td>Default </td><td>16 (Linux, Mac OS X), 8 (Windows) </td></tr>
<tr>
<td></td><td>Min-Max </td><td>2-64 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The number of the audio buffers used by the driver. This number of buffers, multiplied by the buffer size (see setting audio.period-size), determines the maximum latency of the audio driver. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.period-size </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>64 (Linux, Mac OS X), 512 (Windows) </td></tr>
<tr>
<td></td><td>Min-Max </td><td>64-8192 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The size of the audio buffers (in frames). </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.realtime-prio </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>60 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>0-99 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Sets the realtime scheduling priority of the audio synthesis thread (0 disables high priority scheduling). Linux is the only platform which currently makes use of different priority levels. Drivers which use this option: alsa, oss and pulseaudio </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.sample-format </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"16bits" </td></tr>
<tr>
<td></td><td>Options </td><td>"16bits", "float" </td></tr>
<tr>
<td></td><td>Description </td><td>The format of the audio samples. This is currently only an indication; the audio driver may ignore this setting if it can't handle the specified format. </td></tr>
</table>
<p>The following table describes audio driver specific settings.</p>
<a class="anchor" id=""></a>
<table border="1" cellspacing="0">
<caption>Table 3. Audio driver specific settings</caption>
<tr>
<td>audio.alsa.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Options </td><td>ALSA device string, such as: "hw:0", "plughw:1", etc. </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Selects the ALSA audio device to use. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.coreaudio.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Selects the CoreAudio device to use. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.dart.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Selects the Dart (OS/2 driver) device to use. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.dsound.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Selects the DirectSound (Windows) device to use. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.file.endian </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>'auto' if libsndfile support is built in, 'cpu' otherwise. </td></tr>
<tr>
<td></td><td>Options </td><td>auto, big, cpu, little ('cpu' is all that is supported if libsndfile support is not built in) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Defines the byte order when using the 'file' driver or file renderer to store audio to a file. 'auto' uses the default for the given file type, 'cpu' uses the CPU byte order, 'big' uses big endian byte order and 'little' uses little endian byte order. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.file.format </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>s16 </td></tr>
<tr>
<td></td><td>Options </td><td>double, float, s16, s24, s32, s8, u8 ('s16' is all that is supported if libsndfile support not built in) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Defines the audio format when rendering audio to a file. 'double' is 64 bit floating point, 'float' is 32 bit floating point, 's16' is 16 bit signed PCM, 's24' is 24 bit signed PCM, 's32' is 32 bit signed PCM, 's8' is 8 bit signed PCM and 'u8' is 8 bit unsigned PCM. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.file.name </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>'fluidsynth.wav' if libsndfile support is built in, 'fluidsynth.raw' otherwise. </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Specifies the file name to store the audio to, when rendering audio to a file. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.file.type </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>'auto' if libsndfile support is built in, 'raw' otherwise. </td></tr>
<tr>
<td></td><td>Options </td><td>aiff, au, auto, avr, caf, flac, htk, iff, mat, oga, paf, pvf, raw, sd2, sds, sf, voc, w64, wav, xi (actual list of types may vary and depends on the libsndfile library used, 'raw' is the only type available if no libsndfile support is built in). </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Sets the file type of the file which the audio will be stored to. 'auto' attempts to determine the file type from the audio.file.name file extension and falls back to 'wav' if the extension doesn't match any types. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.jack.autoconnect </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>0 (FALSE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">If 1 (TRUE), then FluidSynth output is automatically connected to jack system audio output. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.jack.id </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>fluidsynth </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">ID used when creating Jack client connection. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.jack.multi </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>0 (FALSE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">If 1 (TRUE), then multi-channel Jack output will be enabled if synth.audio-channels is greater than 1. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.jack.server </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td></td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Jack server to connect to. Defaults to an empty string, which uses default Jack server. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.oss.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>/dev/dsp </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Device to use for OSS audio output. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.portaudio.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>PortAudio Default </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Device to use for PortAudio driver output. Note that 'PortAudio Default' is a special value which outputs to the default PortAudio device. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.pulseaudio.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Device to use for PulseAudio driver output </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.pulseaudio.server </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td>Server to use for PulseAudio driver output </td></tr>
</table>
<h1><a class="anchor" id="UsingSynth"></a>
Using the synthesizer without an audio driver</h1>
<p>It is possible to use the synthesizer object without creating an audio driver. This is desirable if the application using FluidSynth manages the audio output itself. The synthesizer has several API functions that can be used to obtain the audio output:</p>
<p><a class="el" href="synth_8h.html#a0d7c287342eb282d4ec63ea7f35cd791" title="Synthesize a block of 16 bit audio samples to audio buffers. ">fluid_synth_write_s16()</a> fills two buffers (left and right channel) with samples coded as signed 16 bits (the endian-ness is machine dependent). <a class="el" href="synth_8h.html#ac86a79a943fc5d5d485ccc5a5fcad03d" title="Synthesize a block of floating point audio samples to audio buffers. ">fluid_synth_write_float()</a> fills a left and right audio buffer with 32 bits floating point samples. For multi channel audio output, the function <a class="el" href="synth_8h.html#a2e394b30908133eed97fe903d5654bac" title="Synthesize a block of floating point audio to separate audio buffers (multichannel rendering)...">fluid_synth_nwrite_float()</a> has to be used.</p>
<p>The function <a class="el" href="synth_8h.html#a1ac90e2732aa652679305f78cbd66670" title="Synthesize floating point audio to audio buffers. ">fluid_synth_process()</a> is still experimental and its use is therefore not recommended but it will probably become the generic interface in future versions.</p>
<h1><a class="anchor" id="LoadingSoundfonts"></a>
Loading and managing SoundFonts</h1>
<p>Before any sound can be produced, the synthesizer needs a SoundFont.</p>
<p>SoundFonts are loaded with the <a class="el" href="synth_8h.html#aaf9376cf7189f9c64da5ffdeed85c9c4" title="Load a SoundFont file (filename is interpreted by SoundFont loaders). ">fluid_synth_sfload()</a> function. The function takes the path to a SoundFont file and a boolean to indicate whether the presets of the MIDI channels should be updated after the SoundFont is loaded. When the boolean value is TRUE, all MIDI channel bank and program numbers will be refreshed, which may cause new instruments to be selected from the newly loaded SoundFont.</p>
<p>The synthesizer can load any number of SoundFonts. The loaded SoundFonts are treated as a stack, where each new loaded SoundFont is placed at the top of the stack. When selecting presets by bank and program numbers, SoundFonts are searched beginning at the top of the stack. In the case where there are presets in different SoundFonts with identical bank and program numbers, the preset from the most recently loaded SoundFont is used. The <a class="el" href="synth_8h.html#ac783362b155fc9c3997f7fd3cf9b1d7f" title="Select an instrument on a MIDI channel by SoundFont ID, bank and program numbers. ...">fluid_synth_program_select()</a> can be used for unambiguously selecting a preset or bank offsets could be applied to each SoundFont with <a class="el" href="synth_8h.html#a8b533b00ff0884d3a2bb3f61abfe7682" title="Offset the bank numbers of a loaded SoundFont, i.e. subtract offset from any bank number when assigni...">fluid_synth_set_bank_offset()</a>, to try and ensure that each preset has unique bank and program numbers.</p>
<p>The <a class="el" href="synth_8h.html#aaf9376cf7189f9c64da5ffdeed85c9c4" title="Load a SoundFont file (filename is interpreted by SoundFont loaders). ">fluid_synth_sfload()</a> function returns the unique identifier of the loaded SoundFont, or -1 in case of an error. This identifier is used in subsequent management functions: <a class="el" href="synth_8h.html#a212bb602e9022c8d8cdb4bc5957f7693" title="Unload a SoundFont. ">fluid_synth_sfunload()</a> removes the SoundFont, <a class="el" href="synth_8h.html#a578273544b162af97633430b5c9b23ae" title="Reload a SoundFont. ">fluid_synth_sfreload()</a> reloads the SoundFont. When a SoundFont is reloaded, it retains it's ID and position on the SoundFont stack.</p>
<p>Additional API functions are provided to get the number of loaded SoundFonts and to get a pointer to the SoundFont.</p>
<h1><a class="anchor" id="SendingMIDI"></a>
Sending MIDI Events</h1>
<p>Once the synthesizer is up and running and a SoundFont is loaded, most people will want to do something useful with it. Make noise, for example. MIDI messages can be sent using the <a class="el" href="synth_8h.html#a4a98222fe1c36bfd598dc4cd89f4b75c" title="Send a note-on event to a FluidSynth object. ">fluid_synth_noteon()</a>, <a class="el" href="synth_8h.html#a5e8f96cacbc6460f7677a6191cbd4472" title="Send a note-off event to a FluidSynth object. ">fluid_synth_noteoff()</a>, <a class="el" href="synth_8h.html#a96b535f5acee6f807033d6cc9ccab555" title="Send a MIDI controller event on a MIDI channel. ">fluid_synth_cc()</a>, <a class="el" href="synth_8h.html#ad5341f8e7c86835b197628f84a2d2c90" title="Set the MIDI pitch bend controller value on a MIDI channel. ">fluid_synth_pitch_bend()</a>, <a class="el" href="synth_8h.html#adb4df1ba450816d42ef40a16b2993549" title="Set MIDI pitch wheel sensitivity on a MIDI channel. ">fluid_synth_pitch_wheel_sens()</a>, and <a class="el" href="synth_8h.html#aad8df89a90669268b6bee09da40088a6" title="Send a program change event on a MIDI channel. ">fluid_synth_program_change()</a> functions. For convenience, there's also a <a class="el" href="synth_8h.html#a97b0f45f00922a46b1c1961d5b1f8cb5" title="Set instrument bank number on a MIDI channel. ">fluid_synth_bank_select()</a> function (the bank select message is normally sent using a control change message).</p>
<p>The following example show a generic graphical button that plays a note when clicked:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>SoundButton : <span class="keyword">public</span> SomeButton</div><div class="line">{</div><div class="line"><span class="keyword">public</span>: </div><div class="line"></div><div class="line"> SoundButton() : SomeButton() {</div><div class="line"> <span class="keywordflow">if</span> (!_synth) {</div><div class="line"> initSynth();</div><div class="line"> }</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="keyword">static</span> <span class="keywordtype">void</span> initSynth() {</div><div class="line"> _settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949">new_fluid_settings</a>();</div><div class="line"> _synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178">new_fluid_synth</a>(_settings);</div><div class="line"> _adriver = <a class="code" href="audio_8h.html#a4ad51317b10b89bfe94ade5db345864b">new_fluid_audio_driver</a>(_settings, _synth);</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="comment">/* ... */</span></div><div class="line"></div><div class="line"> <span class="keyword">virtual</span> <span class="keywordtype">int</span> handleMouseDown(<span class="keywordtype">int</span> x, <span class="keywordtype">int</span> y) {</div><div class="line"> <span class="comment">/* Play a note on key 60 with velocity 100 on MIDI channel 0 */</span></div><div class="line"> <a class="code" href="synth_8h.html#a4a98222fe1c36bfd598dc4cd89f4b75c">fluid_synth_noteon</a>(_synth, 0, 60, 100);</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="keyword">virtual</span> <span class="keywordtype">int</span> handleMouseUp(<span class="keywordtype">int</span> x, <span class="keywordtype">int</span> y) {</div><div class="line"> <span class="comment">/* Release the note on key 60 */</span></div><div class="line"> <a class="code" href="synth_8h.html#a5e8f96cacbc6460f7677a6191cbd4472">fluid_synth_noteoff</a>(_synth, 0, 60);</div><div class="line"> }</div><div class="line"></div><div class="line"><span class="keyword">protected</span>:</div><div class="line"></div><div class="line"> <span class="keyword">static</span> <a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba">fluid_settings_t</a>* _settings;</div><div class="line"> <span class="keyword">static</span> <a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4">fluid_synth_t</a>* _synth;</div><div class="line"> <span class="keyword">static</span> <a class="code" href="types_8h.html#ac3706330ce49cac5b7dd079e90d376d8">fluid_audio_driver_t</a>* _adriver;</div><div class="line">};</div></div><!-- fragment --><h1><a class="anchor" id="RealtimeMIDI"></a>
Creating a Real-time MIDI Driver</h1>
<p>FluidSynth can process real-time MIDI events received from hardware MIDI ports or other applications. To do so, the client must create a MIDI input driver. It is a very similar process to the creation of the audio driver: you initialize some properties in a settings instance and call the <a class="el" href="midi_8h.html#ad0971af69fb51398d468b151cba70bee" title="Create a new MIDI driver instance. ">new_fluid_midi_driver()</a> function providing a callback function that will be invoked when a MIDI event is received. The following MIDI drivers are currently supported:</p>
<ul>
<li>jack: JACK Audio Connection Kit MIDI driver (Linux, Mac OS X)</li>
<li>oss: Open Sound System raw MIDI (Linux, Unix)</li>
<li>alsa_raw: ALSA raw MIDI interface (Linux)</li>
<li>alsa_seq: ALSA sequencer MIDI interface (Linux)</li>
<li>winmidi: Microsoft Windows MM System (Windows)</li>
<li>midishare: MIDI Share (Linux, Mac OS X)</li>
<li>coremidi: Apple CoreMIDI (Mac OS X)</li>
</ul>
<div class="fragment"><div class="line"><span class="preprocessor">#include <fluidsynth.h></span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> handle_midi_event(<span class="keywordtype">void</span>* data, <a class="code" href="types_8h.html#a61c72b76e3ee344637994c3071f74d94">fluid_midi_event_t</a>* event)</div><div class="line">{</div><div class="line"> printf(<span class="stringliteral">"event type: %d\n"</span>, <a class="code" href="midi_8h.html#a63c2b0009873e8a1761f3a3365b12244">fluid_midi_event_get_type</a>(event));</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv)</div><div class="line">{</div><div class="line"> <a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba">fluid_settings_t</a>* settings;</div><div class="line"> <a class="code" href="types_8h.html#ab0f64d7ed81d7361e9600e4a480828df">fluid_midi_driver_t</a>* mdriver;</div><div class="line"> settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949">new_fluid_settings</a>();</div><div class="line"> mdriver = <a class="code" href="midi_8h.html#ad0971af69fb51398d468b151cba70bee">new_fluid_midi_driver</a>(settings, handle_midi_event, NULL);</div><div class="line"> <span class="comment">/* ... */</span> </div><div class="line"> <a class="code" href="midi_8h.html#afe4c8e3657f654edde69e89ea87784eb">delete_fluid_midi_driver</a>(mdriver);</div><div class="line"> <span class="keywordflow">return</span> 0;</div><div class="line">}</div></div><!-- fragment --><p>There are a number of general MIDI driver settings. The midi.driver setting defines the MIDI subsystem that will be used. There are additional settings for the MIDI subsystems used, which are described in a following table.</p>
<a class="anchor" id=""></a>
<table border="1" cellspacing="0">
<caption>Table 4. General MIDI driver settings</caption>
<tr>
<td>midi.driver </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>alsa_seq (Linux), winmidi (Windows), jack (Mac OS X) </td></tr>
<tr>
<td></td><td>Options </td><td>alsa_raw, alsa_seq, coremidi, jack, midishare, oss, winmidi </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The MIDI system to be used. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.realtime-prio </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>50 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>0-99 </td></tr>
<tr>
<td></td><td>Description </td><td>Sets the realtime scheduling priority of the MIDI thread (0 disables high priority scheduling). Linux is the only platform which currently makes use of different priority levels. Drivers which use this option: alsa_raw, alsa_seq, oss </td></tr>
</table>
<p>The following table defines MIDI driver specific settings.</p>
<a class="anchor" id=""></a>
<table border="1" cellspacing="0">
<caption>Table 5. MIDI driver specific settings</caption>
<tr>
<td>midi.alsa.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">ALSA MIDI device to use for RAW ALSA MIDI driver. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.alsa_seq.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">ALSA sequencer device to use for ALSA sequencer driver. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.alsa_seq.id </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>pid </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">ID to use when registering ports with the ALSA sequencer driver. If set to "pid" then the ID will be "FLUID Synth (PID)", where PID is the FluidSynth process ID of the audio thread otherwise the provided string will be used in place of PID. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.jack.id </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>fluidsynth-midi </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Client ID to use with the Jack MIDI driver. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.jack.server </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td></td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Jack server to connect to for Jack MIDI driver. If an empty string then the default server will be used. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.oss.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>/dev/midi </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Device to use for OSS MIDI driver. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.portname </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td></td></tr>
<tr>
<td></td><td>Description </td><td>Used by coremidi and alsa_seq drivers for the portnames registered with the MIDI subsystem. </td></tr>
</table>
<h1><a class="anchor" id="MIDIPlayer"></a>
Loading and Playing a MIDI file</h1>
<p>FluidSynth can be used to play MIDI files, using the MIDI File Player interface. It follows a high level implementation, though its implementation is currently incomplete. After initializing the synthesizer, create the player passing the synth instance to <a class="el" href="midi_8h.html#a6a8628edc77c83c6865fde4b1c296773" title="Create a new MIDI player. ">new_fluid_player()</a>. Then, you can add some SMF file names to the player using <a class="el" href="midi_8h.html#a1ac5b59e4ab9d0f48e917dda0a9a4403" title="Add a MIDI file to a player queue. ">fluid_player_add()</a>, and finally call <a class="el" href="midi_8h.html#a5ac629c8667dbf4eba2cf75d72e134e0" title="Activates play mode for a MIDI player if not already playing. ">fluid_player_play()</a> to start the playback. You can check if the player has finished by calling <a class="el" href="midi_8h.html#ad9b5bd5dcacaa1c967275f537e2add26" title="Get MIDI player status. ">fluid_player_get_status()</a>, or wait for the player to terminate using <a class="el" href="midi_8h.html#a78a49a72e02c2aafe41687dc3a59f533" title="Wait for a MIDI player to terminate (when done playing). ">fluid_player_join()</a>.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <fluidsynth.h></span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv) </div><div class="line">{</div><div class="line"> <span class="keywordtype">int</span> i;</div><div class="line"> <a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba">fluid_settings_t</a>* settings;</div><div class="line"> <a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4">fluid_synth_t</a>* synth;</div><div class="line"> <a class="code" href="types_8h.html#af6c718e19d8c9c6632cb8ffac6974d80">fluid_player_t</a>* player;</div><div class="line"> <a class="code" href="types_8h.html#ac3706330ce49cac5b7dd079e90d376d8">fluid_audio_driver_t</a>* adriver;</div><div class="line"> settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949">new_fluid_settings</a>();</div><div class="line"> synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178">new_fluid_synth</a>(settings);</div><div class="line"> player = <a class="code" href="midi_8h.html#a6a8628edc77c83c6865fde4b1c296773">new_fluid_player</a>(synth);</div><div class="line"> adriver = <a class="code" href="audio_8h.html#a4ad51317b10b89bfe94ade5db345864b">new_fluid_audio_driver</a>(settings, synth);</div><div class="line"> <span class="comment">/* process command line arguments */</span></div><div class="line"> <span class="keywordflow">for</span> (i = 1; i < argc; i++) {</div><div class="line"> <span class="keywordflow">if</span> (<a class="code" href="misc_8h.html#a09b28945cdc794f1f9b5c8edb34fcd6e">fluid_is_soundfont</a>(argv[i])) {</div><div class="line"> <a class="code" href="synth_8h.html#aaf9376cf7189f9c64da5ffdeed85c9c4">fluid_synth_sfload</a>(synth, argv[1], 1);</div><div class="line"> }</div><div class="line"> <span class="keywordflow">if</span> (<a class="code" href="misc_8h.html#abf08bf4bb750d787d551559471069fdf">fluid_is_midifile</a>(argv[i])) {</div><div class="line"> <a class="code" href="midi_8h.html#a1ac5b59e4ab9d0f48e917dda0a9a4403">fluid_player_add</a>(player, argv[i]);</div><div class="line"> }</div><div class="line"> }</div><div class="line"> <span class="comment">/* play the midi files, if any */</span></div><div class="line"> <a class="code" href="midi_8h.html#a5ac629c8667dbf4eba2cf75d72e134e0">fluid_player_play</a>(player);</div><div class="line"> <span class="comment">/* wait for playback termination */</span></div><div class="line"> <a class="code" href="midi_8h.html#a78a49a72e02c2aafe41687dc3a59f533">fluid_player_join</a>(player);</div><div class="line"> <span class="comment">/* cleanup */</span></div><div class="line"> <a class="code" href="audio_8h.html#a05678e633d37da0f93000045393e9442">delete_fluid_audio_driver</a>(adriver);</div><div class="line"> <a class="code" href="midi_8h.html#a678a3d103532b86dada3d2cd111fed0a">delete_fluid_player</a>(player);</div><div class="line"> <a class="code" href="synth_8h.html#a585a63f3a25b9df17b82ae87f2d38cfc">delete_fluid_synth</a>(synth);</div><div class="line"> <a class="code" href="settings_8h.html#a550270f09e4f3c645cbe9e6d3c514ca4">delete_fluid_settings</a>(settings);</div><div class="line"> <span class="keywordflow">return</span> 0;</div><div class="line">}</div></div><!-- fragment --><p>Settings which the MIDI player uses are documented below.</p>
<a class="anchor" id=""></a>
<table border="1" cellspacing="0">
<caption>Table 6. General MIDI driver settings</caption>
<tr>
<td>player.reset-synth </td><td>type </td><td>boolean </td></tr>
<tr>
<td></td><td>default </td><td>1 (TRUE) </td></tr>
<tr>
<td></td><td>description </td><td><p class="starttd">If true, reset the synth before starting a new MIDI song, so the state of a previous song can't affect the new song. Turn it off for seamless looping of a song. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>player.timing-source </td><td>type </td><td>string </td></tr>
<tr>
<td></td><td>default </td><td>'sample' </td></tr>
<tr>
<td></td><td>options </td><td>'sample', 'system' </td></tr>
<tr>
<td></td><td>description </td><td>Determines the timing source of the player sequencer. 'sample' uses the sample clock (how much audio has been output) to sequence events, in which case audio is synchronized with MIDI events. 'system' uses the system clock, audio and MIDI are not synchronized exactly. </td></tr>
</table>
<h1><a class="anchor" id="FileRenderer"></a>
Fast file renderer for non-realtime MIDI file rendering</h1>
<p>Instead of creating an audio driver as described in section <a class="el" href="index.html#MIDIPlayer">Loading and Playing a MIDI file</a> one may chose to use the file renderer, which is the fastest way to synthesize MIDI files.</p>
<div class="fragment"><div class="line"><a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba">fluid_settings_t</a>* settings;</div><div class="line"><a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4">fluid_synth_t</a>* synth;</div><div class="line"><a class="code" href="types_8h.html#af6c718e19d8c9c6632cb8ffac6974d80">fluid_player_t</a>* player;</div><div class="line"><a class="code" href="types_8h.html#a8e8a634da121763271ed819dfe866b3d">fluid_file_renderer_t</a>* renderer;</div><div class="line"></div><div class="line">settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949">new_fluid_settings</a>();</div><div class="line"></div><div class="line"><span class="comment">// specify the file to store the audio to</span></div><div class="line"><span class="comment">// make sure you compiled fluidsynth with libsndfile to get a real wave file</span></div><div class="line"><span class="comment">// otherwise this file will only contain raw s16 stereo PCM</span></div><div class="line"><a class="code" href="settings_8h.html#a855e6038c9946b206156eb1947746032">fluid_settings_setstr</a>(settings, <span class="stringliteral">"audio.file.name"</span>, <span class="stringliteral">"/path/to/output.wav"</span>);</div><div class="line"></div><div class="line"><span class="comment">// use number of samples processed as timing source, rather than the system timer</span></div><div class="line"><a class="code" href="settings_8h.html#a855e6038c9946b206156eb1947746032">fluid_settings_setstr</a>(settings, <span class="stringliteral">"player.timing-source"</span>, <span class="stringliteral">"sample"</span>);</div><div class="line"></div><div class="line"><span class="comment">// since this is a non-realtime szenario, there is no need to pin the sample data</span></div><div class="line"><a class="code" href="settings_8h.html#a26e4192ab084382492589f2c5d8b2e2f">fluid_settings_setint</a>(settings, <span class="stringliteral">"synth.lock-memory"</span>, 0);</div><div class="line"></div><div class="line">synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178">new_fluid_synth</a>(settings);</div><div class="line"></div><div class="line"><span class="comment">// *** loading of a soundfont omitted ***</span></div><div class="line"></div><div class="line">player = <a class="code" href="midi_8h.html#a6a8628edc77c83c6865fde4b1c296773">new_fluid_player</a>(synth);</div><div class="line"><a class="code" href="midi_8h.html#a1ac5b59e4ab9d0f48e917dda0a9a4403">fluid_player_add</a>(player, <span class="stringliteral">"/path/to/midifile.mid"</span>);</div><div class="line"><a class="code" href="midi_8h.html#a5ac629c8667dbf4eba2cf75d72e134e0">fluid_player_play</a>(player);</div><div class="line"></div><div class="line">renderer = <a class="code" href="audio_8h.html#a9d9338a870c5f71ba6fad6db7d17a93e">new_fluid_file_renderer</a> (synth);</div><div class="line"></div><div class="line"><span class="keywordflow">while</span> (<a class="code" href="midi_8h.html#ad9b5bd5dcacaa1c967275f537e2add26">fluid_player_get_status</a>(player) == <a class="code" href="midi_8h.html#a5ec93766f61465dedbbac9bdb76ced83a98ece3a92210189eaad462edc8545bc5">FLUID_PLAYER_PLAYING</a>)</div><div class="line">{</div><div class="line"> <span class="keywordflow">if</span> (<a class="code" href="audio_8h.html#abdea2fb753cf1a5fa9b5dca38c177d80">fluid_file_renderer_process_block</a>(renderer) != <a class="code" href="misc_8h.html#ae4efb1c3ce0d550c922504adfb0fb886">FLUID_OK</a>)</div><div class="line"> {</div><div class="line"> <span class="keywordflow">break</span>;</div><div class="line"> }</div><div class="line">}</div><div class="line"></div><div class="line"><span class="comment">// just for sure: stop the playback explicitly and wait until finished</span></div><div class="line"><a class="code" href="midi_8h.html#a24f5a512dcef6ee34b963366c0a61b33">fluid_player_stop</a>(player);</div><div class="line"><a class="code" href="midi_8h.html#a78a49a72e02c2aafe41687dc3a59f533">fluid_player_join</a>(player);</div><div class="line"></div><div class="line"><a class="code" href="audio_8h.html#a6893d780de15030366e2399293ed7362">delete_fluid_file_renderer</a>(renderer);</div><div class="line"><a class="code" href="midi_8h.html#a678a3d103532b86dada3d2cd111fed0a">delete_fluid_player</a>(player);</div><div class="line"><a class="code" href="synth_8h.html#a585a63f3a25b9df17b82ae87f2d38cfc">delete_fluid_synth</a>(synth);</div><div class="line"><a class="code" href="settings_8h.html#a550270f09e4f3c645cbe9e6d3c514ca4">delete_fluid_settings</a>(settings);</div></div><!-- fragment --><p>Various output files types are supported, if compiled with libsndfile. Those can be specified via the <code>settings</code> object as well. Refer to the documentation of the <code>audio.file.*</code> options.</p>
<h1><a class="anchor" id="MIDIPlayerMem"></a>
Playing a MIDI file from memory</h1>
<p>FluidSynth can be also play MIDI files directly from a buffer in memory. If you need to play a file from a stream (such as stdin, a network, or a high-level file interface), you can load the entire file into a buffer first, and then use this approach. Use the same technique as above, but rather than calling <a class="el" href="midi_8h.html#a1ac5b59e4ab9d0f48e917dda0a9a4403" title="Add a MIDI file to a player queue. ">fluid_player_add()</a>, load it into memory and call <a class="el" href="midi_8h.html#af379c5c85ce8d4399f38c5a382ad13cc" title="Add a MIDI file to a player queue, from a buffer in memory. ">fluid_player_add_mem()</a> instead. Once you have passed a buffer to <a class="el" href="midi_8h.html#af379c5c85ce8d4399f38c5a382ad13cc" title="Add a MIDI file to a player queue, from a buffer in memory. ">fluid_player_add_mem()</a>, it is copied, so you may use it again or free it immediately (it is your responsibility to free it if you allocated it).</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <stdlib.h></span></div><div class="line"><span class="preprocessor">#include <string.h></span></div><div class="line"><span class="preprocessor">#include <fluidsynth.h></span></div><div class="line"></div><div class="line"><span class="comment">/* An example midi file */</span></div><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> MIDIFILE[] = {</div><div class="line"> 0x4d, 0x54, 0x68, 0x64, 0x00, 0x00, 0x00, 0x06,</div><div class="line"> 0x00, 0x01, 0x00, 0x01, 0x01, 0xe0, 0x4d, 0x54,</div><div class="line"> 0x72, 0x6b, 0x00, 0x00, 0x00, 0x20, 0x00, 0x90,</div><div class="line"> 0x3c, 0x64, 0x87, 0x40, 0x80, 0x3c, 0x7f, 0x00,</div><div class="line"> 0x90, 0x43, 0x64, 0x87, 0x40, 0x80, 0x43, 0x7f,</div><div class="line"> 0x00, 0x90, 0x48, 0x64, 0x87, 0x40, 0x80, 0x48,</div><div class="line"> 0x7f, 0x83, 0x60, 0xff, 0x2f, 0x00</div><div class="line">};</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv)</div><div class="line">{</div><div class="line"> <span class="keywordtype">int</span> i;</div><div class="line"> <span class="keywordtype">void</span>* buffer;</div><div class="line"> <span class="keywordtype">size_t</span> buffer_len;</div><div class="line"> <a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba">fluid_settings_t</a>* settings;</div><div class="line"> <a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4">fluid_synth_t</a>* synth;</div><div class="line"> <a class="code" href="types_8h.html#af6c718e19d8c9c6632cb8ffac6974d80">fluid_player_t</a>* player;</div><div class="line"> <a class="code" href="types_8h.html#ac3706330ce49cac5b7dd079e90d376d8">fluid_audio_driver_t</a>* adriver;</div><div class="line"> settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949">new_fluid_settings</a>();</div><div class="line"> synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178">new_fluid_synth</a>(settings);</div><div class="line"> player = <a class="code" href="midi_8h.html#a6a8628edc77c83c6865fde4b1c296773">new_fluid_player</a>(synth);</div><div class="line"> adriver = <a class="code" href="audio_8h.html#a4ad51317b10b89bfe94ade5db345864b">new_fluid_audio_driver</a>(settings, synth);</div><div class="line"> <span class="comment">/* process command line arguments */</span></div><div class="line"> <span class="keywordflow">for</span> (i = 1; i < argc; i++) {</div><div class="line"> <span class="keywordflow">if</span> (<a class="code" href="misc_8h.html#a09b28945cdc794f1f9b5c8edb34fcd6e">fluid_is_soundfont</a>(argv[i])) {</div><div class="line"> <a class="code" href="synth_8h.html#aaf9376cf7189f9c64da5ffdeed85c9c4">fluid_synth_sfload</a>(synth, argv[1], 1);</div><div class="line"> }</div><div class="line"> }</div><div class="line"> <span class="comment">/* queue up the in-memory midi file */</span></div><div class="line"> <a class="code" href="midi_8h.html#af379c5c85ce8d4399f38c5a382ad13cc">fluid_player_add_mem</a>(player, MIDIFILE, <span class="keyword">sizeof</span>(MIDIFILE));</div><div class="line"> <span class="comment">/* play the midi file */</span></div><div class="line"> <a class="code" href="midi_8h.html#a5ac629c8667dbf4eba2cf75d72e134e0">fluid_player_play</a>(player);</div><div class="line"> <span class="comment">/* wait for playback termination */</span></div><div class="line"> <a class="code" href="midi_8h.html#a78a49a72e02c2aafe41687dc3a59f533">fluid_player_join</a>(player);</div><div class="line"> <span class="comment">/* cleanup */</span></div><div class="line"> <a class="code" href="audio_8h.html#a05678e633d37da0f93000045393e9442">delete_fluid_audio_driver</a>(adriver);</div><div class="line"> <a class="code" href="midi_8h.html#a678a3d103532b86dada3d2cd111fed0a">delete_fluid_player</a>(player);</div><div class="line"> <a class="code" href="synth_8h.html#a585a63f3a25b9df17b82ae87f2d38cfc">delete_fluid_synth</a>(synth);</div><div class="line"> <a class="code" href="settings_8h.html#a550270f09e4f3c645cbe9e6d3c514ca4">delete_fluid_settings</a>(settings);</div><div class="line"> <span class="keywordflow">return</span> 0;</div><div class="line">}</div></div><!-- fragment --><h1><a class="anchor" id="MIDIRouter"></a>
Real-time MIDI router</h1>
<p>The MIDI router is one more processing layer directly behind the MIDI input. It processes incoming MIDI events and generates control events for the synth. It can be used to filter or modify events prior to sending them to the synthesizer. When created, the MIDI router is transparent and simply passes all MIDI events. Router "rules" must be added to actually make use of its capabilities.</p>
<p>Some examples of MIDI router usage:</p>
<ul>
<li>Filter messages (Example: Pass sustain pedal CCs only to selected channels)</li>
<li>Split the keyboard (Example: noteon with notenr < x: to ch 1, >x to ch 2)</li>
<li>Layer sounds (Example: for each noteon received on ch 1, create a noteon on ch1, ch2, ch3,...)</li>
<li>Velocity scaling (Example: for each noteon event, scale the velocity by 1.27)</li>
<li>Velocity switching (Example: v <= 100: "Angel Choir"; v > 100: "Hell's Bells")</li>
<li>Get rid of aftertouch</li>
</ul>
<p>The MIDI driver API has a clean separation between the midi thread and the synthesizer. That opens the door to add a midi router module.</p>
<p>MIDI events coming from the MIDI player do not pass through the MIDI router.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <fluidsynth.h></span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv) </div><div class="line">{</div><div class="line"> <a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba">fluid_settings_t</a>* settings;</div><div class="line"> <a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4">fluid_synth_t</a>* synth;</div><div class="line"> <a class="code" href="types_8h.html#aa57b4746220e24506a169f109875e4ad">fluid_midi_router_t</a>* router;</div><div class="line"> <a class="code" href="types_8h.html#a3154253ddb8f9b8f8f737c91f5973278">fluid_midi_router_rule_t</a>* rule;</div><div class="line"></div><div class="line"> settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949">new_fluid_settings</a>();</div><div class="line"> synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178">new_fluid_synth</a>(settings);</div><div class="line"></div><div class="line"> <span class="comment">/* Create the MIDI router and pass events to the synthesizer */</span></div><div class="line"> router = <a class="code" href="midi_8h.html#ae28ddf804fa5ba108a65c24fcf6e9813">new_fluid_midi_router</a> (settings, <a class="code" href="synth_8h.html#a439e1175fa34123b3d0c96a0366d42dd">fluid_synth_handle_midi_event</a>, synth);</div><div class="line"></div><div class="line"> <span class="comment">/* Clear default rules */</span></div><div class="line"> <a class="code" href="midi_8h.html#a57aed5e84828c202452e13f265dd72f7">fluid_midi_router_clear_rules</a> (router);</div><div class="line"></div><div class="line"> <span class="comment">/* Add rule to map all notes < MIDI note #60 on any channel to channel 4 */</span></div><div class="line"> rule = <a class="code" href="midi_8h.html#a128bc8b126cbabf7717149123815d235">new_fluid_midi_router_rule</a> ();</div><div class="line"> <a class="code" href="midi_8h.html#acc264709865c1e2dc972528cca55dc6f">fluid_midi_router_rule_set_chan</a> (rule, 0, 15, 0.0, 4); <span class="comment">/* Map all to channel 4 */</span></div><div class="line"> <a class="code" href="midi_8h.html#ac4f572c218943ded7fe43692a265ddb5">fluid_midi_router_rule_set_param1</a> (rule, 0, 59, 1.0, 0); <span class="comment">/* Match notes < 60 */</span></div><div class="line"> <a class="code" href="midi_8h.html#aa1894a103cde4f1efe80c7c9d5096ae2">fluid_midi_router_add_rule</a> (router, rule, <a class="code" href="midi_8h.html#ab798a0a5b95607556c9ecfbeaaab962ba44d3968ac6d884210bdace219f17c684">FLUID_MIDI_ROUTER_RULE_NOTE</a>);</div><div class="line"></div><div class="line"> <span class="comment">/* Add rule to map all notes >= MIDI note #60 on any channel to channel 5 */</span></div><div class="line"> rule = <a class="code" href="midi_8h.html#a128bc8b126cbabf7717149123815d235">new_fluid_midi_router_rule</a> ();</div><div class="line"> <a class="code" href="midi_8h.html#acc264709865c1e2dc972528cca55dc6f">fluid_midi_router_rule_set_chan</a> (rule, 0, 15, 0.0, 5); <span class="comment">/* Map all to channel 5 */</span></div><div class="line"> <a class="code" href="midi_8h.html#ac4f572c218943ded7fe43692a265ddb5">fluid_midi_router_rule_set_param1</a> (rule, 60, 127, 1.0, 0); <span class="comment">/* Match notes >= 60 */</span></div><div class="line"> <a class="code" href="midi_8h.html#aa1894a103cde4f1efe80c7c9d5096ae2">fluid_midi_router_add_rule</a> (router, rule, <a class="code" href="midi_8h.html#ab798a0a5b95607556c9ecfbeaaab962ba44d3968ac6d884210bdace219f17c684">FLUID_MIDI_ROUTER_RULE_NOTE</a>);</div><div class="line"></div><div class="line"> <span class="comment">/* Add rule to reverse direction of pitch bender on channel 7 */</span></div><div class="line"> rule = <a class="code" href="midi_8h.html#a128bc8b126cbabf7717149123815d235">new_fluid_midi_router_rule</a> ();</div><div class="line"> <a class="code" href="midi_8h.html#acc264709865c1e2dc972528cca55dc6f">fluid_midi_router_rule_set_chan</a> (rule, 7, 7, 1.0, 0); <span class="comment">/* Match channel 7 only */</span></div><div class="line"> <a class="code" href="midi_8h.html#ac4f572c218943ded7fe43692a265ddb5">fluid_midi_router_rule_set_param1</a> (rule, 0, 16383, -1.0, 16383); <span class="comment">/* Reverse pitch bender */</span></div><div class="line"> <a class="code" href="midi_8h.html#aa1894a103cde4f1efe80c7c9d5096ae2">fluid_midi_router_add_rule</a> (router, rule, <a class="code" href="midi_8h.html#ab798a0a5b95607556c9ecfbeaaab962ba087309f49bb501d67d74a9d5a128e621">FLUID_MIDI_ROUTER_RULE_PITCH_BEND</a>);</div><div class="line"></div><div class="line"> <span class="comment">/* ... Create audio driver, process events, etc ... */</span></div><div class="line"></div><div class="line"> <span class="comment">/* cleanup */</span></div><div class="line"> <a class="code" href="midi_8h.html#a48f3cd2fcebc5f80c8a9ce43973b9fdc">delete_fluid_midi_router</a>(router);</div><div class="line"> <a class="code" href="synth_8h.html#a585a63f3a25b9df17b82ae87f2d38cfc">delete_fluid_synth</a>(synth);</div><div class="line"> <a class="code" href="settings_8h.html#a550270f09e4f3c645cbe9e6d3c514ca4">delete_fluid_settings</a>(settings);</div><div class="line"> <span class="keywordflow">return</span> 0;</div><div class="line">}</div></div><!-- fragment --><h1><a class="anchor" id="Sequencer"></a>
Sequencer</h1>
<p>FluidSynth's sequencer can be used to play MIDI events in a more flexible way than using the MIDI file player, which expects the events to be stored as Standard MIDI Files. Using the sequencer, you can provide the events one by one, with an optional timestamp for scheduling.</p>
<p>The client program should first initialize the sequencer instance using the function <a class="el" href="seq_8h.html#a3c27499606024a92bca0b32dbcf72c44" title="Create a new sequencer object. ">new_fluid_sequencer2()</a>. There is a complementary function <a class="el" href="seq_8h.html#a57d2277b188240e435b5fc3f39c0bc7e" title="Free a sequencer object. ">delete_fluid_sequencer()</a> to delete it. After creating the sequencer instance, the destinations can be registered using <a class="el" href="seqbind_8h.html#ae18ee23fd409270c9da4f0cd5c557c3d" title="Registers a synthesizer as a destination client of the given sequencer. ">fluid_sequencer_register_fluidsynth()</a> for the synthesizer destination, and optionally using <a class="el" href="seq_8h.html#af48b466b7b2e97a438b166ae194b248c" title="Register a sequencer client. ">fluid_sequencer_register_client()</a> for the client destination providing a suitable callback function. It can be unregistered using <a class="el" href="seq_8h.html#a8e84c1295e097b59b2aad0c6b4654050" title="Unregister a previously registered client. ">fluid_sequencer_unregister_client()</a>. After the initialization, events can be sent with <a class="el" href="seq_8h.html#ac6c0346378a9ce531ec428747dbe16fe" title="Send an event immediately. ">fluid_sequencer_send_now()</a> and scheduled to the future with <a class="el" href="seq_8h.html#afb0c62f3a2cff3decbf628535f4511ef" title="Schedule an event for sending at a later time. ">fluid_sequencer_send_at()</a>. The registration functions return identifiers, that can be used as destinations of an event using <a class="el" href="event_8h.html#adb65323ce4cc44441be32fb5f2dc958a" title="Set destination of this sequencer event, i.e. ">fluid_event_set_dest()</a>.</p>
<p>The function <a class="el" href="seq_8h.html#a2a51cf34c359020eb6c9b7ab549ab239" title="Get the current tick of a sequencer. ">fluid_sequencer_get_tick()</a> returns the current playing position. A program may choose a new timescale in milliseconds using <a class="el" href="seq_8h.html#aa62f856223ff035fcfca2517facc3205" title="Set the time scale of a sequencer. ">fluid_sequencer_set_time_scale()</a>.</p>
<p>The following example uses the fluidsynth sequencer to implement a sort of music box. FluidSynth internal clock is used to schedule repetitive sequences of notes. The next sequence is scheduled on advance before the end of the current one, using a timer event that triggers a callback function. The scheduling times are always absolute values, to avoid slippage.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "fluidsynth.h"</span></div><div class="line"></div><div class="line"><a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4">fluid_synth_t</a>* synth;</div><div class="line"><a class="code" href="types_8h.html#ac3706330ce49cac5b7dd079e90d376d8">fluid_audio_driver_t</a>* adriver;</div><div class="line"><a class="code" href="types_8h.html#a7c7acad4ee620fc954a7ad4d7e87e1c3">fluid_sequencer_t</a>* sequencer;</div><div class="line"><span class="keywordtype">short</span> synthSeqID, mySeqID;</div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> now;</div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> seqduration;</div><div class="line"></div><div class="line"><span class="comment">// prototype</span></div><div class="line"><span class="keywordtype">void</span> seq_callback(<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> time, <a class="code" href="types_8h.html#aca09348be1b6e6ee7fce49dd4734f1ba">fluid_event_t</a>* event, <a class="code" href="types_8h.html#a7c7acad4ee620fc954a7ad4d7e87e1c3">fluid_sequencer_t</a>* seq, <span class="keywordtype">void</span>* data);</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> createsynth() </div><div class="line">{</div><div class="line"> <a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba">fluid_settings_t</a>* settings;</div><div class="line"> settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949">new_fluid_settings</a>();</div><div class="line"> <a class="code" href="settings_8h.html#a855e6038c9946b206156eb1947746032">fluid_settings_setstr</a>(settings, <span class="stringliteral">"synth.reverb.active"</span>, <span class="stringliteral">"yes"</span>);</div><div class="line"> <a class="code" href="settings_8h.html#a855e6038c9946b206156eb1947746032">fluid_settings_setstr</a>(settings, <span class="stringliteral">"synth.chorus.active"</span>, <span class="stringliteral">"no"</span>);</div><div class="line"> synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178">new_fluid_synth</a>(settings);</div><div class="line"> adriver = <a class="code" href="audio_8h.html#a4ad51317b10b89bfe94ade5db345864b">new_fluid_audio_driver</a>(settings, synth);</div><div class="line"> sequencer = <a class="code" href="seq_8h.html#a3c27499606024a92bca0b32dbcf72c44">new_fluid_sequencer2</a>(0);</div><div class="line"></div><div class="line"> <span class="comment">// register synth as first destination</span></div><div class="line"> synthSeqID = <a class="code" href="seqbind_8h.html#ae18ee23fd409270c9da4f0cd5c557c3d">fluid_sequencer_register_fluidsynth</a>(sequencer, synth);</div><div class="line"></div><div class="line"> <span class="comment">// register myself as second destination</span></div><div class="line"> mySeqID = <a class="code" href="seq_8h.html#af48b466b7b2e97a438b166ae194b248c">fluid_sequencer_register_client</a>(sequencer, <span class="stringliteral">"me"</span>, seq_callback, NULL);</div><div class="line"></div><div class="line"> <span class="comment">// the sequence duration, in ms</span></div><div class="line"> seqduration = 1000;</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> deletesynth() </div><div class="line">{</div><div class="line"> <a class="code" href="seq_8h.html#a57d2277b188240e435b5fc3f39c0bc7e">delete_fluid_sequencer</a>(sequencer);</div><div class="line"> <a class="code" href="audio_8h.html#a05678e633d37da0f93000045393e9442">delete_fluid_audio_driver</a>(adriver);</div><div class="line"> <a class="code" href="synth_8h.html#a585a63f3a25b9df17b82ae87f2d38cfc">delete_fluid_synth</a>(synth);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> loadsoundfont() </div><div class="line">{</div><div class="line"> <span class="keywordtype">int</span> fluid_res;</div><div class="line"> <span class="comment">// put your own path here</span></div><div class="line"> fluid_res = <a class="code" href="synth_8h.html#aaf9376cf7189f9c64da5ffdeed85c9c4">fluid_synth_sfload</a>(synth, <span class="stringliteral">"Inside:VintageDreamsWaves-v2.sf2"</span>, 1);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> sendnoteon(<span class="keywordtype">int</span> chan, <span class="keywordtype">short</span> key, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> date) </div><div class="line">{</div><div class="line"> <span class="keywordtype">int</span> fluid_res;</div><div class="line"> <a class="code" href="types_8h.html#aca09348be1b6e6ee7fce49dd4734f1ba">fluid_event_t</a> *evt = <a class="code" href="event_8h.html#a1d535480f26630b755102415a6d246cb">new_fluid_event</a>();</div><div class="line"> <a class="code" href="event_8h.html#abe9c6ec481cfd9791d5290a4aa4101df">fluid_event_set_source</a>(evt, -1);</div><div class="line"> <a class="code" href="event_8h.html#adb65323ce4cc44441be32fb5f2dc958a">fluid_event_set_dest</a>(evt, synthSeqID);</div><div class="line"> <a class="code" href="event_8h.html#a1337c75403ebf9c43607a3f3139c6bba">fluid_event_noteon</a>(evt, chan, key, 127);</div><div class="line"> fluid_res = <a class="code" href="seq_8h.html#afb0c62f3a2cff3decbf628535f4511ef">fluid_sequencer_send_at</a>(sequencer, evt, date, 1);</div><div class="line"> <a class="code" href="event_8h.html#a473c54f0c43bdea789b211c23c7daeee">delete_fluid_event</a>(evt);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> schedule_next_callback() </div><div class="line">{</div><div class="line"> <span class="keywordtype">int</span> fluid_res;</div><div class="line"> <span class="comment">// I want to be called back before the end of the next sequence</span></div><div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> callbackdate = now + seqduration/2;</div><div class="line"> <a class="code" href="types_8h.html#aca09348be1b6e6ee7fce49dd4734f1ba">fluid_event_t</a> *evt = <a class="code" href="event_8h.html#a1d535480f26630b755102415a6d246cb">new_fluid_event</a>();</div><div class="line"> <a class="code" href="event_8h.html#abe9c6ec481cfd9791d5290a4aa4101df">fluid_event_set_source</a>(evt, -1);</div><div class="line"> <a class="code" href="event_8h.html#adb65323ce4cc44441be32fb5f2dc958a">fluid_event_set_dest</a>(evt, mySeqID);</div><div class="line"> <a class="code" href="event_8h.html#aa99a8c9110e819b53fc42baa0bfd8fbf">fluid_event_timer</a>(evt, NULL);</div><div class="line"> fluid_res = <a class="code" href="seq_8h.html#afb0c62f3a2cff3decbf628535f4511ef">fluid_sequencer_send_at</a>(sequencer, evt, callbackdate, 1);</div><div class="line"> <a class="code" href="event_8h.html#a473c54f0c43bdea789b211c23c7daeee">delete_fluid_event</a>(evt);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> schedule_next_sequence() {</div><div class="line"> <span class="comment">// Called more or less before each sequence start</span></div><div class="line"> <span class="comment">// the next sequence start date</span></div><div class="line"> now = now + seqduration;</div><div class="line"></div><div class="line"> <span class="comment">// the sequence to play</span></div><div class="line"></div><div class="line"> <span class="comment">// the beat : 2 beats per sequence</span></div><div class="line"> sendnoteon(0, 60, now + seqduration/2);</div><div class="line"> sendnoteon(0, 60, now + seqduration);</div><div class="line"></div><div class="line"> <span class="comment">// melody</span></div><div class="line"> sendnoteon(1, 45, now + seqduration/10);</div><div class="line"> sendnoteon(1, 50, now + 4*seqduration/10);</div><div class="line"> sendnoteon(1, 55, now + 8*seqduration/10);</div><div class="line"></div><div class="line"> <span class="comment">// so that we are called back early enough to schedule the next sequence</span></div><div class="line"> schedule_next_callback();</div><div class="line">}</div><div class="line"></div><div class="line"><span class="comment">/* sequencer callback */</span></div><div class="line"><span class="keywordtype">void</span> seq_callback(<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> time, <a class="code" href="types_8h.html#aca09348be1b6e6ee7fce49dd4734f1ba">fluid_event_t</a>* event, <a class="code" href="types_8h.html#a7c7acad4ee620fc954a7ad4d7e87e1c3">fluid_sequencer_t</a>* seq, <span class="keywordtype">void</span>* data) {</div><div class="line"> schedule_next_sequence();</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">void</span>) {</div><div class="line"> createsynth();</div><div class="line"> loadsoundfont();</div><div class="line"></div><div class="line"> <span class="comment">// initialize our absolute date</span></div><div class="line"> now = <a class="code" href="seq_8h.html#a2a51cf34c359020eb6c9b7ab549ab239">fluid_sequencer_get_tick</a>(sequencer);</div><div class="line"> schedule_next_sequence();</div><div class="line"></div><div class="line"> sleep(100000);</div><div class="line"> deletesynth();</div><div class="line"> <span class="keywordflow">return</span> 0;</div><div class="line">}</div></div><!-- fragment --><h1><a class="anchor" id="Shell"></a>
Shell interface</h1>
<p>The shell interface allows you to send simple textual commands to the synthesizer, to parse a command file, or to read commands from the stdin or other input streams. To find the list of currently supported commands, please check the fluid_cmd.c file or type "help" in the fluidsynth command line shell.</p>
<a class="anchor" id=""></a>
<table border="1" cellspacing="0">
<caption>Table 7. General MIDI driver settings</caption>
<tr>
<td>shell.prompt </td><td>type </td><td>string </td></tr>
<tr>
<td></td><td>default </td><td>"" </td></tr>
<tr>
<td></td><td>description </td><td>In dump mode we set the prompt to "". the ui cannot easily handle lines, which don't end with cr. changing the prompt cannot be done through a command, because the current shell does not handle empty arguments. </td></tr>
<tr>
<td>shell.port </td><td>type </td><td>number </td></tr>
<tr>
<td></td><td>default </td><td>9800 </td></tr>
<tr>
<td></td><td>min-max </td><td>1-65535 </td></tr>
<tr>
<td></td><td>description </td><td>The shell can be used in a client/server mode. This setting controls what TCP/IP port the server uses. </td></tr>
</table>
<h1><a class="anchor" id="Advanced"></a>
Advanced features, not yet documented. API reference may contain more info.</h1>
<ul>
<li>Accessing low-level voice parameters</li>
<li>Reverb settings</li>
<li>Chorus settings</li>
<li>Interpolation settings (set_gen, get_gen, NRPN)</li>
<li>Voice overflow settings</li>
<li>LADSPA effects unit</li>
<li>Multi-channel audio</li>
<li>MIDI tunings </li>
</ul>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>