docbase/instrument_scripts/01_instrument_scripts.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>Instrument Scripts</title>
    <meta name="description" content="Introduction to real-time instrument scripts.">
    <link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css">
    <script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script>
  </head>
  <body>
    <h1>Real-Time Instrument Scripts</h1>
    <p>
      The sampler technology is constantly evolving to satisfy new feature
      requirements of sound designer in order to allow them creating more and
      more realistic sounds. As an example you might look at state of the art
      orchestra libraries. They not only allow you pick one of the individual
      instrument sounds of an orchestra, they also allow you to control the
      articulation of the respective orchestra instrument while playing them
      live with your keyboard. So you might start playing an interesting intro
      with a string ensemble in
      <i title="Technique that uses a bowing style that leaves the string clearly to produce a light 'bouncing' sound.">spiccato</i>
      playing style, then you might go over into a slow bridge part where the
      string ensemble is resembling a
      <i title="Of successive notes in performance, connected without any intervening silence of articulation.">legato</i>
      articulation or even
      <i title="Portamento is a continous pitch sliding from one note to another.">portamento</i>
      in between, which makes that part of the song very calm and
      relaxed, and then you shock your audience all of a sudden with a loud
      <i title="Staccato signifies a note of shortened duration, separated from the note that may follow by silence.">staccato</i>,
      automatically supported by kettledrum and brass sounds, that wakes up even
      the last one in the back row. And the best thing: you did not switch to
      another instrument during that entire song.
    </p>

    <h3>Technical Challenge</h3>
    <p>
      Adding these kinds of features to a sampler had long been a challenge for
      software developers. On one hand you need to provide the musician
      additional controls to let him switch between such kind of orchestra
      articulations. Sound designers came up with various ideas to let the
      keyboard player do this. For example by
      <ul>
        <li>using continous controllers like the keyboard's modulation wheel</li>
        <li>using a dedicated keys section on the keyboard where each key selects another playing style</li>
        <li>utilizing aftertouch support of keyboards</li>
      </ul>
      and some more. And on the other hand developers needed to extend the
      sampler software and the instrument file format to deal with all those
      extensions. Thinking about <i>portamento</i> for example, the sampler not
      only has to pick the right sample for the first key the keyboard player
      hits, the sampler also has to detect the next note and needs to pick a
      special dedicated portamento sample that goes specifically from that one
      note to that other note. If the sampler would do that synthetically
      instead, then it would sound synthetically.
    </p>
    <p>
      And if that was not enough, sound designers started even to ask for very
      exotic features, specifically for just a bunch of sounds or even for just
      one single sound of
      theirs, for example
      a specific note pattern that shall automatically be added by the sampler
      to each note being played by the keyboard player.
      The requested feature set became such large, that sampler developers
      failed to put all this into their stock sampler software package.
      A completely new solution was required.
    </p>

    <h3>Scripts as Solution</h3>
    <p>
      Instead of bloating the sampler engine with more and more suboptimal
      features that not really suited anybody, the sampler developers turned the
      way around and opened the sampler engine for sound designers, so that they
      could add their own custom software components and bundle them with their
      sounds. These kinds of software plugins that are directly glued and
      shipped with sounds are called <i>Instrument Scripts</i>, they extend
      the sampler software with new software features required by the
      respective sound.
    </p>
    <p>
      Sound designers were finally free to add their own features to the sampler
      and used <i>Instrument Scripts</i> extensively to create stunning new
      sounds. For example they came up with a feature called
      <i title="Sympathetic resonance is a harmonic phenomenon wherein a formerly passive string responds to external vibrations to which it has a harmonic likeness.">
        symphatetic resonance
      </i> for their piano sound libraries, which brought piano sounds another
      great leap forward to match their real, physical counter parts.
    </p>
    
    <h2>Using Scripts with LinuxSampler</h2>
    <p>
      LinuxSampler allows you to write and use such <i>Instrument Scripts</i>
      as well. At the moment support for instrument scripts is provided by
      the GigaStudio format engine, as well as now also by the SFZ format engine of
      LinuxSampler. The script engine was developed in a very modular design,
      where most of the script engine's software is independent from the
      actual sampler format and the respective sampler format engine is just
      adding its format specific extensions to the script language. For example
      the GigaStudio format engine adds scripting functions to allow the sound
      designer to control the dimension region by scripts.
    </p>

    <h3>Bundling Scripts with GigaStudio (.gig) Files</h3>
    <p>
      Our graphical instrument editor for the GigaStudio format - <i>gigedit</i> -
      includes an instrument script editor and allows you to attach
      instrument scripts to individual GigaStudio format sounds. Refer to the
      gigedit manual for <a href="gigedit_scripts.html">how to manage instrument scripts with gigedit.</a>
    </p>

    <h3>Bundling Scripts with SFZ (.sfz) Files</h3>
    <p>
      LinuxSampler adds a new opcode <code lang="sfz">script</code> as an
      extension to the offical SFZ format. Similar to the <code lang="sfz">sample</code>
      opcode, a file system path needs to be assigned to the actual script file that should
      be loaded by the sampler. The <code lang="sfz">script</code> opcode should be placed
      in the SFZ file's <code lang="sfz">&lt;global&gt;</code> section. However at the moment
      the precise location of the opcode will simply be ignored by LinuxSampler. A simple example
      SFZ file may look like this:
    </p>
    <code lang="sfz">
// real-time instrument scripts should be loaded in global section
&lt;global&gt;
script=path/to/my_nksp_script.txt

// just load one audio file and assign in to entire key range
&lt;group&gt;
sample=some_sound.wav
    </code>
    <p>
      At the moment LinuxSampler supports only one script file per instrument.
      Accordingly there should only be one <code lang="sfz">script</code> opcode
      occurrence in your SFZ file. If you place more than one
      <code lang="sfz">script</code> opcode to a SFZ file, then only the first
      script will be loaded and the sampler will print a warning. In future this will
      change, and the sampler will support running multiple scripts, and will run
      the scripts subsequently on events according to the order the scripts appeared
      in the SFZ file.
    </p>

    <h3>Learning the Script Language</h3>
    <p>
      You certainly find some instrument scripts ready to be used on the
      Internet. So you can simply download and attach them to your sounds with
      <i>gigedit</i>. In order to write your own custom instrument scripts though, you
      need to get in touch with the scripting language. Refer to the
      <a href="nksp.html">NKSP Language Tour</a>
      for learning how to write your own scripts.
    </p>

    <h3>Script Language Reference</h3>
    <p>
      If you are already familiar with the instrument script language basics,
      and just need details and examples to the individual built-in functions
      and built-in variables, then refer to the
      <a href="nksp_reference.html">NKSP Reference Manual</a>.
    </p>

  </body>
</html>
1	schoenebeck	2732	<html>
2			<head>
3			<meta name="author" content="Christian Schoenebeck">
4			<title>Instrument Scripts</title>
5			<meta name="description" content="Introduction to real-time instrument scripts.">
6	schoenebeck	2738	<link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css">
7			<script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script>
8	schoenebeck	2732	</head>
9			<body>
10			<h1>Real-Time Instrument Scripts</h1>
11			<p>
12			The sampler technology is constantly evolving to satisfy new feature
13			requirements of sound designer in order to allow them creating more and
14			more realistic sounds. As an example you might look at state of the art
15			orchestra libraries. They not only allow you pick one of the individual
16			instrument sounds of an orchestra, they also allow you to control the
17			articulation of the respective orchestra instrument while playing them
18			live with your keyboard. So you might start playing an interesting intro
19			with a string ensemble in
20			<i title="Technique that uses a bowing style that leaves the string clearly to produce a light 'bouncing' sound.">spiccato</i>
21			playing style, then you might go over into a slow bridge part where the
22			string ensemble is resembling a
23			<i title="Of successive notes in performance, connected without any intervening silence of articulation.">legato</i>
24			articulation or even
25			<i title="Portamento is a continous pitch sliding from one note to another.">portamento</i>
26			in between, which makes that part of the song very calm and
27			relaxed, and then you shock your audience all of a sudden with a loud
28			<i title="Staccato signifies a note of shortened duration, separated from the note that may follow by silence.">staccato</i>,
29			automatically supported by kettledrum and brass sounds, that wakes up even
30			the last one in the back row. And the best thing: you did not switch to
31			another instrument during that entire song.
32			</p>
33
34			<h3>Technical Challenge</h3>
35			<p>
36			Adding these kinds of features to a sampler had long been a challenge for
37			software developers. On one hand you need to provide the musician
38			additional controls to let him switch between such kind of orchestra
39			articulations. Sound designers came up with various ideas to let the
40			keyboard player do this. For example by
41			<ul>
42			<li>using continous controllers like the keyboard's modulation wheel</li>
43			<li>using a dedicated keys section on the keyboard where each key selects another playing style</li>
44			<li>utilizing aftertouch support of keyboards</li>
45			</ul>
46			and some more. And on the other hand developers needed to extend the
47			sampler software and the instrument file format to deal with all those
48			extensions. Thinking about <i>portamento</i> for example, the sampler not
49			only has to pick the right sample for the first key the keyboard player
50			hits, the sampler also has to detect the next note and needs to pick a
51			special dedicated portamento sample that goes specifically from that one
52			note to that other note. If the sampler would do that synthetically
53			instead, then it would sound synthetically.
54			</p>
55			<p>
56			And if that was not enough, sound designers started even to ask for very
57			exotic features, specifically for just a bunch of sounds or even for just
58			one single sound of
59			theirs, for example
60			a specific note pattern that shall automatically be added by the sampler
61			to each note being played by the keyboard player.
62			The requested feature set became such large, that sampler developers
63			failed to put all this into their stock sampler software package.
64			A completely new solution was required.
65			</p>
66
67			<h3>Scripts as Solution</h3>
68			<p>
69			Instead of bloating the sampler engine with more and more suboptimal
70			features that not really suited anybody, the sampler developers turned the
71			way around and opened the sampler engine for sound designers, so that they
72			could add their own custom software components and bundle them with their
73			sounds. These kinds of software plugins that are directly glued and
74			shipped with sounds are called <i>Instrument Scripts</i>, they extend
75			the sampler software with new software features required by the
76			respective sound.
77			</p>
78			<p>
79			Sound designers were finally free to add their own features to the sampler
80			and used <i>Instrument Scripts</i> extensively to create stunning new
81			sounds. For example they came up with a feature called
82			<i title="Sympathetic resonance is a harmonic phenomenon wherein a formerly passive string responds to external vibrations to which it has a harmonic likeness.">
83			symphatetic resonance
84			</i> for their piano sound libraries, which brought piano sounds another
85			great leap forward to match their real, physical counter parts.
86			</p>
87
88			<h2>Using Scripts with LinuxSampler</h2>
89			<p>
90			LinuxSampler allows you to write and use such <i>Instrument Scripts</i>
91	schoenebeck	3083	as well. At the moment support for instrument scripts is provided by
92			the GigaStudio format engine, as well as now also by the SFZ format engine of
93			LinuxSampler. The script engine was developed in a very modular design,
94			where most of the script engine's software is independent from the
95			actual sampler format and the respective sampler format engine is just
96			adding its format specific extensions to the script language. For example
97			the GigaStudio format engine adds scripting functions to allow the sound
98			designer to control the dimension region by scripts.
99	schoenebeck	2732	</p>
100
101	schoenebeck	3083	<h3>Bundling Scripts with GigaStudio (.gig) Files</h3>
102	schoenebeck	2732	<p>
103			Our graphical instrument editor for the GigaStudio format - <i>gigedit</i> -
104			includes an instrument script editor and allows you to attach
105			instrument scripts to individual GigaStudio format sounds. Refer to the
106			gigedit manual for <a href="gigedit_scripts.html">how to manage instrument scripts with gigedit.</a>
107			</p>
108
109	schoenebeck	3083	<h3>Bundling Scripts with SFZ (.sfz) Files</h3>
110			<p>
111			LinuxSampler adds a new opcode <code lang="sfz">script</code> as an
112			extension to the offical SFZ format. Similar to the <code lang="sfz">sample</code>
113			opcode, a file system path needs to be assigned to the actual script file that should
114			be loaded by the sampler. The <code lang="sfz">script</code> opcode should be placed
115			in the SFZ file's <code lang="sfz"><global></code> section. However at the moment
116			the precise location of the opcode will simply be ignored by LinuxSampler. A simple example
117			SFZ file may look like this:
118			</p>
119			<code lang="sfz">
120			// real-time instrument scripts should be loaded in global section
121			<global>
122			script=path/to/my_nksp_script.txt
123
124			// just load one audio file and assign in to entire key range
125			<group>
126			sample=some_sound.wav
127			</code>
128			<p>
129			At the moment LinuxSampler supports only one script file per instrument.
130			Accordingly there should only be one <code lang="sfz">script</code> opcode
131			occurrence in your SFZ file. If you place more than one
132			<code lang="sfz">script</code> opcode to a SFZ file, then only the first
133			script will be loaded and the sampler will print a warning. In future this will
134			change, and the sampler will support running multiple scripts, and will run
135			the scripts subsequently on events according to the order the scripts appeared
136			in the SFZ file.
137			</p>
138
139	schoenebeck	2732	<h3>Learning the Script Language</h3>
140			<p>
141			You certainly find some instrument scripts ready to be used on the
142			Internet. So you can simply download and attach them to your sounds with
143			<i>gigedit</i>. In order to write your own custom instrument scripts though, you
144			need to get in touch with the scripting language. Refer to the
145			<a href="nksp.html">NKSP Language Tour</a>
146			for learning how to write your own scripts.
147			</p>
148
149			<h3>Script Language Reference</h3>
150			<p>
151			If you are already familiar with the instrument script language basics,
152			and just need details and examples to the individual built-in functions
153			and built-in variables, then refer to the
154			<a href="nksp_reference.html">NKSP Reference Manual</a>.
155			</p>
156
157			</body>
158			</html>