Reggae tutorial: Saving audio in user selected format - Revision history

Krashan: /* Saver Control Without GUI */ Image added.

2012-10-09T11:37:02Z

‎Saver Control Without GUI: Image added.

Krashan: /* Yet Another Example */

2012-10-08T19:32:04Z

‎Yet Another Example

Krashan: /* Yet Another Example */

2012-10-08T19:30:45Z

‎Yet Another Example

Krashan: /* Yet Another Example */

2012-10-08T19:29:10Z

‎Yet Another Example

Krashan at 19:28, 8 October 2012

2012-10-08T19:28:11Z

Krashan: /* Saver Control Without GUI */

2012-10-08T19:10:24Z

‎Saver Control Without GUI

Krashan: /* Saver Control Without GUI */

2012-10-08T18:58:11Z

‎Saver Control Without GUI

Krashan: textual control

2012-10-08T17:32:01Z

textual control

Krashan: /* Memory Bufer as Data Source */

2012-10-04T15:28:41Z

‎Memory Bufer as Data Source

Krashan: /* Encoder, Muxer and their Setup */

2012-10-04T12:41:18Z

‎Encoder, Muxer and their Setup

@@ Line 152: / Line 152: @@
 * applications using fixed output format
 This lower level control is implemented as an argument string. This string contains the audio format specification in textual, human readable form, very similar to form of arguments of MorphOS shell commands. In fact Reggae argument string is parsed with the same function as shell arguments, namely ''ReadArgs()'' from ''dos.library''. To say more, even when application builds a Reggae saver chain from GUI, argument string is used internally as an intermediate stage.
 How one builds a Reggae saver from an argument string? There is a function in ''multimedia.class'', named ''MediaBuildFromArgsTags()''. It works exactly the same as ''MediaBuildFromGuiTags()'', the only difference is it takes argument string instead of GUI object. But how the argument string looks like? Let's look at a simple example:

@@ Line 172: / Line 172: @@
 The third example application using Reggae saver API is [http://krashan.ppa.pl/articles/zgrzytor Zgrzytor]. Unlike Zormanita and U1Synth, it is a shell command using textual saver description explained in the previous section. Zgrzytor is a simple noise generator using a shift register with EXOR feedback. It is a well known technique for generate periodic sounds (for short register) or pseudorandom noise (for long register). User can specify taps (bits) of the shift register where EXOR gate feeding back the register is connected. Sampling rate of output, output file name and output format can be also specified. Some example Zgrzytor call may be:
-  Zgrzytor 3 11 22050 '''WAVE BITS=32'''
+  Zgrzytor 3 11 22050 somenoise.wav '''WAVE BITS=32'''
 This will attach EXOR to bits 3 and 11 (bits are counted from feed side and from 1) of the shift register and generate 5 seconds (time is hardcoded inside program) of noise, set sampling rate to 22.05 kHz and save as 32-bit WAVE (Zgrzytor works with 32-bit integers, so it can produce "real" 32-bit sound). The last, emboldened part of the call is just Reggae saver argument string. More about Zgrzytor can be found on its homepage. Of course full source code of Zgrzytor is added to the archive.

@@ Line 170: / Line 170: @@
 ==Yet Another Example==
-The third example application using Reggae saver API is [http://krashan.ppa.pl/articles/zgrzytor|Zgrzytor]. Unlike Zormanita ans U1Synth it is a shell command using textual saver description explained in the previous section. Zgrzytor is a simple noise generator using a shift register with EXOR feedback. It is a well known technique for generate periodic sounds (for short register) or pseudorandom noise (for long register). User can specify taps (bits) of the shift register where EXOR gate feeding back the register is connected. Sampling rate of output, output file name and output format can be also specified. Some example Zgrzytor call may be:
+The third example application using Reggae saver API is [http://krashan.ppa.pl/articles/zgrzytor Zgrzytor]. Unlike Zormanita and U1Synth, it is a shell command using textual saver description explained in the previous section. Zgrzytor is a simple noise generator using a shift register with EXOR feedback. It is a well known technique for generate periodic sounds (for short register) or pseudorandom noise (for long register). User can specify taps (bits) of the shift register where EXOR gate feeding back the register is connected. Sampling rate of output, output file name and output format can be also specified. Some example Zgrzytor call may be:
   Zgrzytor 3 11 22050 '''WAVE BITS=32'''
-This will attach EXOR to bits 3 and 11 (bits are counted from feed side and from 1) and generate 5 seconds (time is hardcoded inside program) of noise, set sampling rate to 22.05 kHz and save as 32-bit WAVE (Zgrzytor works with 32-bit integers, so it can produce "real" 32-bit sound). The last, emboldened part of the call is just Reggae saver argument string. More about Zgrzytor can be found on its homepage. Of course full source code of Zgrzytor is added to the archive.
+This will attach EXOR to bits 3 and 11 (bits are counted from feed side and from 1) of the shift register and generate 5 seconds (time is hardcoded inside program) of noise, set sampling rate to 22.05 kHz and save as 32-bit WAVE (Zgrzytor works with 32-bit integers, so it can produce "real" 32-bit sound). The last, emboldened part of the call is just Reggae saver argument string. More about Zgrzytor can be found on its homepage. Of course full source code of Zgrzytor is added to the archive.

← Older revision		Revision as of 19:29, 8 October 2012
Line 174:		Line 174:
	Zgrzytor 3 11 22050 '''WAVE BITS=32'''		Zgrzytor 3 11 22050 '''WAVE BITS=32'''

−	This will attach EXOR to bits 3 and 11 (bits are counted from feed side and from 1) and generate 5 seconds (time is hardcoded inside program) of noise, set sampling rate to 22.05 kHz and save as 32-bit WAVE (Zgrzytor works with 32-bit integers, so it can produce "real" 32-bit sound). More about Zgrzytor on its homepage. Of course full source code of Zgrzytor is added to the archive.	+	This will attach EXOR to bits 3 and 11 (bits are counted from feed side and from 1) and generate 5 seconds (time is hardcoded inside program) of noise, set sampling rate to 22.05 kHz and save as 32-bit WAVE (Zgrzytor works with 32-bit integers, so it can produce "real" 32-bit sound). The last, emboldened part of the call is just Reggae saver argument string. More about Zgrzytor can be found on its homepage. Of course full source code of Zgrzytor is added to the archive.

← Older revision		Revision as of 19:28, 8 October 2012
Line 164:		Line 164:

	Applications wanting to log operations done with GUI, or create some undo history can also retrieve the argument string from GUI object with ''MediaGetArgsFromGui()''. It will generate the argument string basing on current gadgets states.		Applications wanting to log operations done with GUI, or create some undo history can also retrieve the argument string from GUI object with ''MediaGetArgsFromGui()''. It will generate the argument string basing on current gadgets states.
		+
		+	Compared to GUI, the textual interface to Reggae savers has two shortcomings:
		+	* User (or application, if the argument string is not given by user) has to know which multiplexers are installed in the system and has to know encoder parameters.
		+	* GUI is designed in a way, that does not allow user to enter senseless or conflicting combinations of parameters (for example ''rawaudio.muxer'' GUI automatically disables "Byte Order" gadget, when 8-bit samples are selected). For textual definition parameter validation is done when Reggae chain is built, and ''MediaBuildFromArgsTags()'' simply fail when arguments make no sense.
		+
		+	==Yet Another Example==
		+	The third example application using Reggae saver API is [http://krashan.ppa.pl/articles/zgrzytor\|Zgrzytor]. Unlike Zormanita ans U1Synth it is a shell command using textual saver description explained in the previous section. Zgrzytor is a simple noise generator using a shift register with EXOR feedback. It is a well known technique for generate periodic sounds (for short register) or pseudorandom noise (for long register). User can specify taps (bits) of the shift register where EXOR gate feeding back the register is connected. Sampling rate of output, output file name and output format can be also specified. Some example Zgrzytor call may be:
		+
		+	Zgrzytor 3 11 22050 '''WAVE BITS=32'''
		+
		+	This will attach EXOR to bits 3 and 11 (bits are counted from feed side and from 1) and generate 5 seconds (time is hardcoded inside program) of noise, set sampling rate to 22.05 kHz and save as 32-bit WAVE (Zgrzytor works with 32-bit integers, so it can produce "real" 32-bit sound). More about Zgrzytor on its homepage. Of course full source code of Zgrzytor is added to the archive.

@@ Line 157: / Line 157: @@
   WAVE BITS=24
-Every Reggae saver specification consists of two parts. The first part is multiplexer class name, just without the ".muxer" extension. It is capitalized here, but Reggae argument strings are case insensitive. The second part is the rest of string (after skipping whitespaces after multiplexer name. In some cases the second part may be empty, as most formats have default values for encoder parameters. For example one can use simply
+Every Reggae saver specification consists of two parts. The first part is multiplexer class name, just without the ".muxer" extension. It is capitalized here, but Reggae argument strings are case insensitive. The second part is the rest of string (after skipping whitespaces after multiplexer name) so it can contain multiple arguments. In some cases the second part may be empty, as most formats have default values for encoder parameters. For example one can use simply
   AIFF
 to have data stored as 16-bit AIFF file. Of course every multiplexer has its own set of parameters, described in its autodoc.

← Older revision		Revision as of 18:58, 8 October 2012
Line 151:		Line 151:
	* application log/undo		* application log/undo
	* applications using fixed output format		* applications using fixed output format
		+	This lower level control is implemented as an argument string. This string contains the audio format specification in textual, human readable form, very similar to form of arguments of MorphOS shell commands. In fact Reggae argument string is parsed with the same function as shell arguments, namely ''ReadArgs()'' from ''dos.library''. To say more, even when application builds a Reggae saver chain from GUI, argument string is used internally as an intermediate stage.
		+
		+	How one builds a Reggae saver from an argument string? There is a function in ''multimedia.class'', named ''MediaBuildFromArgsTags()''. It works exactly the same as ''MediaBuildFromGuiTags()'', the only difference is it takes argument string instead of GUI object. But how the argument string looks like? Let's look at a simple example:
		+
		+	WAVE BITS=24
		+
		+	Every Reggae saver specification consists of two parts. The first part is multiplexer class name, just without the ".muxer" extension. It is capitalized here, but Reggae argument strings are case insensitive. The second part is the rest of string (after skipping whitespaces after multiplexer name. In some cases the second part may be empty, as most formats have default values for encoder parameters. For example one can use simply
		+
		+	AIFF
		+
		+	to have data stored as 16-bit AIFF file. Of course every multiplexer has its own set of parameters, described in its autodoc.

← Older revision		Revision as of 17:32, 8 October 2012
Line 144:		Line 144:

	Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally, MUI stuff is disposed automatically by MUI.		Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally, MUI stuff is disposed automatically by MUI.
		+
		+	==Saver Control Without GUI==
		+	While the GUI object provided by Reggae for choosing encoder suits most needs of applications, there are cases, where some lower level control is needed. Some examples include (but are not limited to):
		+	* shell commands
		+	* scripting interface
		+	* application log/undo
		+	* applications using fixed output format

@@ Line 51: / Line 51: @@
 ==Building Reggae Processing Chain==
-====Memory Bufer as Data Source====
+====Memory Buffer as Data Source====
 Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

@@ Line 84: / Line 84: @@
 ====Encoder, Muxer and their Setup====
-This step is automatically performed by Reggae . To set up the encoder and multiplexer duo, Reggae needs two sources of information:
+This step is automatically performed by Reggae. To set up the encoder and multiplexer duo, Reggae needs two sources of information:
 * GUI object with all selections made by user.
 * Source data stream.