Reggae tutorial: Playing a sound from memory - Revision history

Krashan: /* Embedding sound in application executable */

2010-06-17T08:12:21Z

‎Embedding sound in application executable

Krashan: /* Embedding sound in application executable */ Some rework.

2010-06-17T08:10:12Z

‎Embedding sound in application executable: Some rework.

Krashan: /* Buffering sound file from disk */ Filled with contents.

2010-06-17T08:05:20Z

‎Buffering sound file from disk: Filled with contents.

Krashan: Structuring the thing.

2010-06-17T07:20:49Z

Structuring the thing.

Krashan: Style++.

2010-06-17T07:10:43Z

Style++.

Krashan: Style++.

2010-06-17T07:09:50Z

Style++.

Krashan: Style++.

2010-06-17T07:09:15Z

Style++.

Krashan: Style.

2010-06-17T07:08:30Z

Style.

Krashan: Removed some trash.

2010-06-17T07:03:21Z

Removed some trash.

Krashan: More contents, the chapter seems to be finished.

2010-06-17T07:02:41Z

More contents, the chapter seems to be finished.

@@ Line 44: / Line 44: @@
 ==Embedding sound in application executable==
-Embedding sound in the code has the advantage of simplicity. The application is more self-contained. There are no disk operations involved, so there is no need for error handling code. On the other hand it can make executable very big, and there is no chance for user to change sounds. Audio file of any fomat can be converted to C code (as a large table) with [http://morphos-files.net/download/BinToC BinToC] tool. Generated source is added to the project and compiled. Then address of the table (denoted in C just as the table name) and its length in bytes, are passed as parameters to ''memory.stream'' object.
+Embedding sound in the code has the advantage of simplicity. The application is more self-contained. There are no disk operations involved, so there is no need for error handling code. On the other hand it can make executable very big, and there is no chance for user to change sounds. Audio file of any fomat can be converted to C code (as a large table) with [http://morphos-files.net/download/BinToC BinToC] tool. Generated source is added to the project and compiled. Then address of the table (denoted in C just as the table name) and its length in bytes, are passed as parameters to ''memory.stream'' object (see code fragment below).
 ==Memory stream as data source==

@@ Line 44: / Line 44: @@
 ==Embedding sound in application executable==
-The second way is a bit dangerous, as it can make the executable very big. On the other hand, such an application is more self contained. Audio file of any fomat can be converted to C code of a large table with [http://morphos-files.net/download/BinToC BinToC] tool. Generated source is added to the project and compiled. Then address of the table (denoted in C just as the table name) and its length in bytes, are passed as parameters to ''memory.stream'' object.
+Embedding sound in the code has the advantage of simplicity. The application is more self-contained. There are no disk operations involved, so there is no need for error handling code. On the other hand it can make executable very big, and there is no chance for user to change sounds. Audio file of any fomat can be converted to C code (as a large table) with [http://morphos-files.net/download/BinToC BinToC] tool. Generated source is added to the project and compiled. Then address of the table (denoted in C just as the table name) and its length in bytes, are passed as parameters to ''memory.stream'' object.
 ==Memory stream as data source==

← Older revision		Revision as of 08:05, 17 June 2010
Line 10:		Line 10:

	==Buffering sound file from disk==		==Buffering sound file from disk==
		+	In this method sounds are stored as files separated from application executable. Memory buffers for sounds are allocated dynamically. This approach allows for easy changing of sounds or – for example – delivering low quality versions for machines having less memory, or even running without sound, when memory is low. The code and error handling is a bit more complicated however. The process of sound buffering does not involve Reggae at all. File is opened and sized, then buffer is allocated, file is read into it and closes. These tasks may be performed by native ''dos.library'' calls (''Open()'', ''Read()'', ''Close()''), or C standard library calls (''fopen()'', ''fread()'', ''fclose()''). As the later ones are just wrappers on native calls, using native ones is recommended, unless code portability is important. The following code buffers a file in memory with minimal error checking:
		+
		+
		+	<tt>BPTR handle;<br>
		+	LONG size;<br>
		+	APTR buffer;<br>
		+	struct FileInfoBlock *fib;<br><br>
		+	if (fib = AllocDosObject(DOS_FIB, NULL))<br>
		+	{<br>
		+	if (handle = Open("PROGDIR:sounds/anysound.wav", MODE_OLDFILE))<br>
		+	{<br>
		+	if (ExamineFH(handle, fib))<br>
		+	{<br>
		+	size = fib->fib_Size;<br><br>
		+	if (buffer = AllocVecTaskPooled(size))<br>
		+	{<br>
		+	if (Read(handle, buffer, size) == size)<br>
		+	{<br>
		+	/* use buffer as memory.stream data here */<br>
		+	}<br>
		+	FreeVecTaskPooled(buffer);<br>
		+	}<br>
		+	}<br>
		+	Close(handle);<br>
		+	}<br>
		+	FreeDosObject(DOS_FIB, fib);<br>
		+	}</tt>
		+
		+	<small>Programmers new to MorphOS may notice some new things in the code above. While not related to Reggae, they are worth some explanation. The first one is ''PROGDIR:'' assign (or link in Unix nomenclature). It just means the directory, where running executable file is located. It is then an easy way to refer to application data with relative paths. When user moves the application directory somewhere, paths using ''PROGDIR:'' are still valid.
		+
		+	The second thing is ''AllocVecTaskPooled()'' call. Every MorphOS process has an automatically assigned memory pool, which is disposed when process ends. Using this pool for allocations, an application need not track them, as all memory not freed explicitly with ''FreeVecTaskPooled()'' will be freed when memory pool is disposed.</small>

	==Embedding sound in application executable==		==Embedding sound in application executable==

@@ Line 1: / Line 1: @@
 ''Grzegorz Kraszewski''
 While [[Reggae tutorial: Playing a sound from file|playing a sound from file]] is the most common way, there are applications where it has several disadvantages. When a sound is short, played many times and low latency is required, playing this sound from memory will be better option. Seeking in the sound, or restarting it will be substantially faster then, as it does not involve any disk activity.
@@ Line 6: / Line 7: @@
 On the other hand playing from memory should be used with care. Audio data are very space consuming usually. Five seconds audio effect stored as PCM in audio CD quality takes 861 kB of memory. A solution for this problem is to use compressed formats and let Reggae decompress it on the fly.
-There are two ways of placing audio file in memory. Firstly, it can be loaded from disk. Secondly the audio file contents may be embedded into the executable file. The second way is a bit dangerous, as it can make the executable very big. On the other hand, such an application is more self contained. Audio file of any fomat can be converted to C code of a large table with [http://morphos-files.net/download/BinToC BinToC] tool. Generated source is added to the project and compiled. Then address of the table (denoted in C just as the table name) and its length in bytes, are passed as parameters to ''memory.stream'' object.
+There are two ways of placing audio file in memory. Firstly, it can be loaded from disk. Secondly the audio file contents may be embedded into the executable file.
 Reggae uses the ''memory.stream'' class to access data located in system memory. Its usage is similar to ''file.stream'', there are some differencies however. The first one is stream name. For ''memory.stream'' it is a string containing stream address as a hexadecimal number, like for example "2749FA0C". ''MMA_StreamName'' attribute is not used often however. One usually has the address just as number, not as text. Converting it to text just to make Reggae to convert it back to number makes not much sense. Then ''MMA_StreamHandle'' attribute comes with help. Its value is just the address of stream, passed as number. Another very important attribute is ''MMA_StreamLength''. Memory based streams have no "natural" end. When one is reading a file, DOS just reports EOF (end of file) condition, when the file ends. In memory one can read endlessly, until he hits the end of physical memory space. That is why ''MMA_StreamLenght'' is a '''required''' attribute for memory streams. Reggae will refuse to create a stream object, if the attribute is not specified. Note also that the attribute in general is '''64-bit''' one, and takes a '''pointer to 64-bit number'''. Passing just a 32-bit number as the value is a common mistake here. Code snippet below shows typical creation of memory stream object from a sound embedded in executable file:
@@ Line 22: / Line 31: @@
 When sound is buffered from file, one has to check the file size first, then allocate a buffer and load the file into it using usual ''dos.library'' calls, or C standard library calls. The process is shown in the [http://krashan.ppa.pl/reggae/library/playaudio_memory.c complete example source code]. After the buffer is loaded, ''memory.stream'' object is created the same way as above.
 To play the sound, one connects created media object with an ''audio.output'' object, exactly the same as for playing from disk. There is also no difference in controlling the playback, or waiting for sound end. Thanks to stream abstraction Reggae "does not care" what the stream is. Just seek and retrigger operations are much faster. It is important for short sound effects retriggered many times (think of a shot sound in a game). The example code linked above allows user for retriggering the sound pressing ENTER key. It can be done very fast without delays, assuming some simple audio compression is used (just press and hold ENTER, retrigger rate will be as fast as key repetition rate set in system preferences).
 The example shows also "launch and forget" strategy of playing sounds with Reggae. There is no check for sound end. ''MMM_Stop()'' just stops and does seek to the start. Then ''MMM_Play()'' starts playback. It does not matter if retrigger happens while previous sound is still playing or not. There is also no sound end check when user stops the program. Disposing an active (playing) ''audio.output'' object is perfectly safe.

← Older revision		Revision as of 07:10, 17 June 2010
Line 8:		Line 8:
	There are two ways of placing audio file in memory. Firstly, it can be loaded from disk. Secondly the audio file contents may be embedded into the executable file. The second way is a bit dangerous, as it can make the executable very big. On the other hand, such an application is more self contained. Audio file of any fomat can be converted to C code of a large table with [http://morphos-files.net/download/BinToC BinToC] tool. Generated source is added to the project and compiled. Then address of the table (denoted in C just as the table name) and its length in bytes, are passed as parameters to ''memory.stream'' object.		There are two ways of placing audio file in memory. Firstly, it can be loaded from disk. Secondly the audio file contents may be embedded into the executable file. The second way is a bit dangerous, as it can make the executable very big. On the other hand, such an application is more self contained. Audio file of any fomat can be converted to C code of a large table with [http://morphos-files.net/download/BinToC BinToC] tool. Generated source is added to the project and compiled. Then address of the table (denoted in C just as the table name) and its length in bytes, are passed as parameters to ''memory.stream'' object.

−	Reggae uses the ''memory.stream'' class to access data located in system memory. Its usage is similar to ''file.stream'', there are some differencies however. The first one is stream name. For ''memory.stream'' it is a string containing stream address as a hexadecimal number, like for example "2749FA0C". ''MMA_StreamName'' attribute is not used often however. One usually has the address just as number, not as text. Converting it to text just to make Reggae to convert it back to number makes not much sense. Then ''MMA_StreamHandle'' attribute comes with help. Its value is just the address of stream, passed as number. Another very important attribute is ''MMA_StreamLength''. Memory based streams have no "natural" end. When one is reading a file, DOS just reports EOF (end of file) condition, when the file ends. In memory one can read endlessly, until he hits end of physical memory space. That is why ''MMA_StreamLenght'' is a '''required''' attribute for memory streams. Reggae will refuse to create a stream object, if the attribute is not specified. Note also that the attribute in general is '''64-bit''' one, and takes a '''pointer to 64-bit number'''. Passing just a 32-bit number as the value is a common mistake here. Code snippet below shows typical creation of memory stream object from a sound embedded in executable file:	+	Reggae uses the ''memory.stream'' class to access data located in system memory. Its usage is similar to ''file.stream'', there are some differencies however. The first one is stream name. For ''memory.stream'' it is a string containing stream address as a hexadecimal number, like for example "2749FA0C". ''MMA_StreamName'' attribute is not used often however. One usually has the address just as number, not as text. Converting it to text just to make Reggae to convert it back to number makes not much sense. Then ''MMA_StreamHandle'' attribute comes with help. Its value is just the address of stream, passed as number. Another very important attribute is ''MMA_StreamLength''. Memory based streams have no "natural" end. When one is reading a file, DOS just reports EOF (end of file) condition, when the file ends. In memory one can read endlessly, until he hits the end of physical memory space. That is why ''MMA_StreamLenght'' is a '''required''' attribute for memory streams. Reggae will refuse to create a stream object, if the attribute is not specified. Note also that the attribute in general is '''64-bit''' one, and takes a '''pointer to 64-bit number'''. Passing just a 32-bit number as the value is a common mistake here. Code snippet below shows typical creation of memory stream object from a sound embedded in executable file:

← Older revision		Revision as of 07:09, 17 June 2010
Line 8:		Line 8:
	There are two ways of placing audio file in memory. Firstly, it can be loaded from disk. Secondly the audio file contents may be embedded into the executable file. The second way is a bit dangerous, as it can make the executable very big. On the other hand, such an application is more self contained. Audio file of any fomat can be converted to C code of a large table with [http://morphos-files.net/download/BinToC BinToC] tool. Generated source is added to the project and compiled. Then address of the table (denoted in C just as the table name) and its length in bytes, are passed as parameters to ''memory.stream'' object.		There are two ways of placing audio file in memory. Firstly, it can be loaded from disk. Secondly the audio file contents may be embedded into the executable file. The second way is a bit dangerous, as it can make the executable very big. On the other hand, such an application is more self contained. Audio file of any fomat can be converted to C code of a large table with [http://morphos-files.net/download/BinToC BinToC] tool. Generated source is added to the project and compiled. Then address of the table (denoted in C just as the table name) and its length in bytes, are passed as parameters to ''memory.stream'' object.

−	Reggae uses the ''memory.stream'' class to access data located in system memory. Its usage is similar to ''file.stream'', there are some differencies however. The first one is stream name. For ''memory.stream'' it is a string containing stream address as a hexadecimal number, like for example "2749FA0C". ''MMA_StreamName'' attribute is not used often however. One usually has the address just as number, not as text. Converting it to text just to make Reggae to convert it back to number makes not much sense. Then ''MMA_StreamHandle'' attribute comes with help. ~~It's~~ value is just the address of stream, passed as number. Another very important attribute is ''MMA_StreamLength''. Memory based streams have no "natural" end. When one is reading a file, DOS just reports EOF (end of file) condition, when the file ends. In memory one can read endlessly, until he hits end of physical memory space. That is why ''MMA_StreamLenght'' is a '''required''' attribute for memory streams. Reggae will refuse to create a stream object, if the attribute is not specified. Note also that the attribute in general is '''64-bit''' one, and takes a '''pointer to 64-bit number'''. Passing just a 32-bit number as the value is a common mistake here. Code snippet below shows typical creation of memory stream object from a sound embedded in executable file:	+	Reggae uses the ''memory.stream'' class to access data located in system memory. Its usage is similar to ''file.stream'', there are some differencies however. The first one is stream name. For ''memory.stream'' it is a string containing stream address as a hexadecimal number, like for example "2749FA0C". ''MMA_StreamName'' attribute is not used often however. One usually has the address just as number, not as text. Converting it to text just to make Reggae to convert it back to number makes not much sense. Then ''MMA_StreamHandle'' attribute comes with help. Its value is just the address of stream, passed as number. Another very important attribute is ''MMA_StreamLength''. Memory based streams have no "natural" end. When one is reading a file, DOS just reports EOF (end of file) condition, when the file ends. In memory one can read endlessly, until he hits end of physical memory space. That is why ''MMA_StreamLenght'' is a '''required''' attribute for memory streams. Reggae will refuse to create a stream object, if the attribute is not specified. Note also that the attribute in general is '''64-bit''' one, and takes a '''pointer to 64-bit number'''. Passing just a 32-bit number as the value is a common mistake here. Code snippet below shows typical creation of memory stream object from a sound embedded in executable file:

← Older revision		Revision as of 07:08, 17 June 2010
Line 2:		Line 2:


−	While [[Reggae tutorial: Playing a sound from file\|playing a sound from file]] is the most common way, there are applications where it has several disadvantages. When a sound is short, played many times and low latency is required, playing this sound from memory will be ~~the~~ better option. Seeking in the sound, or restarting it will be substantially faster then, as it does not involve any disk activity.	+	While [[Reggae tutorial: Playing a sound from file\|playing a sound from file]] is the most common way, there are applications where it has several disadvantages. When a sound is short, played many times and low latency is required, playing this sound from memory will be better option. Seeking in the sound, or restarting it will be substantially faster then, as it does not involve any disk activity.

	On the other hand playing from memory should be used with care. Audio data are very space consuming usually. Five seconds audio effect stored as PCM in audio CD quality takes 861 kB of memory. A solution for this problem is to use compressed formats and let Reggae decompress it on the fly.		On the other hand playing from memory should be used with care. Audio data are very space consuming usually. Five seconds audio effect stored as PCM in audio CD quality takes 861 kB of memory. A solution for this problem is to use compressed formats and let Reggae decompress it on the fly.

← Older revision		Revision as of 07:03, 17 June 2010
Line 26:		Line 26:

	The example shows also "launch and forget" strategy of playing sounds with Reggae. There is no check for sound end. ''MMM_Stop()'' just stops and does seek to the start. Then ''MMM_Play()'' starts playback. It does not matter if retrigger happens while previous sound is still playing or not. There is also no sound end check when user stops the program. Disposing an active (playing) ''audio.output'' object is perfectly safe.		The example shows also "launch and forget" strategy of playing sounds with Reggae. There is no check for sound end. ''MMM_Stop()'' just stops and does seek to the start. Then ''MMM_Play()'' starts playback. It does not matter if retrigger happens while previous sound is still playing or not. There is also no sound end check when user stops the program. Disposing an active (playing) ''audio.output'' object is perfectly safe.
−
−	~~. If retrigger happens while previous sound is still playing, ''MMM_Stop()'' rewinds it immediately and continues from the start.~~

@@ Line 13: / Line 13: @@
 <tt>CONST UBYTE SoundData [12837] =  { /* audio data here */ }; /* The length is just example. */<br>
 QUAD length = 12837;<br>
-Object *stream;<br><br>
+Object *sound;<br><br>
-stream = MediaNewObject(<br>
+sound = MediaNewObject(<br>
 &nbsp;&nbsp;MMA_StreamType, "memory.stream",<br>
 &nbsp;&nbsp;MMA_StreamHandle, SoundData,<br>
 &nbsp;&nbsp;MMA_StreamLength, &length,<br>
 TAG_END);</tt>