Reggae tutorial: Playing a sound from file - Revision history

Polluks: /* Opening a sound file */ link

2025-05-12T11:39:24Z

‎Opening a sound file: link

Krashan at 05:50, 17 June 2010

2010-06-17T05:50:16Z

Krashan: Added author name.

2010-06-17T05:49:54Z

Added author name.

Krashan: /* Waiting for end of sound */ Fixed external link.

2010-06-15T19:55:04Z

‎Waiting for end of sound: Fixed external link.

Krashan: /* Waiting for end of sound */ Finished this section, added examples.

2010-06-15T19:54:06Z

‎Waiting for end of sound: Finished this section, added examples.

Krashan: /* Making noise */ More parentheses.

2010-06-15T18:32:52Z

‎Making noise: More parentheses.

Krashan: /* Making noise */ Parentheses after method names.

2010-06-15T18:32:27Z

‎Making noise: Parentheses after method names.

Krashan: /* Making noise */ Made method name italic.

2010-06-15T18:31:55Z

‎Making noise: Made method name italic.

Krashan: /* Making noise */ "Both methods" -> "All methods", all three of them.

2010-06-15T18:31:21Z

‎Making noise: "Both methods" -> "All methods", all three of them.

Krashan: /* Making noise */ Added MMM_Pause description.

2010-06-14T22:10:40Z

‎Making noise: Added MMM_Pause description.

@@ Line 18: / Line 18: @@
-This single call creates a complete decoding infrastructure for a specified file. Data source is specified by two tags, ''MMA_StreamName'' and ''MMA_StreamType''. The first one is the name of the source. In case of files it is just path to the file, which may be absolute (as in the example), relative to the current directory, or relative to program executable location (using ''PROGDIR:'' [[assign]]). ''MMA_StreamType'' is used to specify which Reggae stream class (or "transport") should be used. Of course ''file.stream'' is for disk based files (and other things recognized by DOS as filesystems).
+This single call creates a complete decoding infrastructure for a specified file. Data source is specified by two tags, ''MMA_StreamName'' and ''MMA_StreamType''. The first one is the name of the source. In case of files it is just path to the file, which may be absolute (as in the example), relative to the current directory, or relative to program executable location (using ''PROGDIR:'' [[Shell Commands/Assign|assign]]). ''MMA_StreamType'' is used to specify which Reggae stream class (or "transport") should be used. Of course ''file.stream'' is for disk based files (and other things recognized by DOS as filesystems).
 The last tag is a kind of filter. If Reggae recognizes the file, but it is not sound, the file will be rejected, and the function will return NULL. Of course if file is not recognized at all, NULL will be returned as well. Checking the result of ''MediaNewObject()'' against NULL is a very good idea.
 In case of success ''media'' contains a pointer to Reggae object, having at least one output data port, port 0.
 ==Creating output==

← Older revision		Revision as of 05:50, 17 June 2010
Line 1:		Line 1:
	''Grzegorz Kraszewski''		''Grzegorz Kraszewski''
		+

	Playing a sound file from disk is one of most common media related tasks. Reggae can perform it with a few lines of code. Using Reggae for audio playback has several advantages:		Playing a sound file from disk is one of most common media related tasks. Reggae can perform it with a few lines of code. Using Reggae for audio playback has several advantages:

← Older revision		Revision as of 05:49, 17 June 2010
Line 1:		Line 1:
		+	''Grzegorz Kraszewski''
		+
	Playing a sound file from disk is one of most common media related tasks. Reggae can perform it with a few lines of code. Using Reggae for audio playback has several advantages:		Playing a sound file from disk is one of most common media related tasks. Reggae can perform it with a few lines of code. Using Reggae for audio playback has several advantages:
	* Wide range of supported audio formats. A codec is selected and loaded by Reggae automatically.		* Wide range of supported audio formats. A codec is selected and loaded by Reggae automatically.

← Older revision		Revision as of 19:55, 15 June 2010
Line 107:		Line 107:
	The main difference between these two methods is that message signalling is "one-shot". After the message is sent to application's port, it must be got from the port and reinitialized before it can be reused again. Signal method may be used repeatedly, which is comfortable when a short sound is triggered multiple times.		The main difference between these two methods is that message signalling is "one-shot". After the message is sent to application's port, it must be got from the port and reinitialized before it can be reused again. Signal method may be used repeatedly, which is comfortable when a short sound is triggered multiple times.

−	[http://krashan.ppa.pl/reggae/library/~~playaudio_signal~~.c A complete example source code using a message]	+	[http://krashan.ppa.pl/reggae/library/playaudio_message.c A complete example source code using a message]

← Older revision		Revision as of 19:54, 15 June 2010
Line 74:		Line 74:
	The class offers two methods for signalling sound end event, namely audio process can send a '''signal''' or can reply a '''message'''. Application specifies method choosen and its parameters by performing one of the two methods described below on ''audio.output'' object. Methods are usually called before the playback is started, but may be also called when object is already playing. The later solution is tricky however, as the sound may be very short, so a method may be called '''after''' the sound end. In this case signalling requests will be never triggered.		The class offers two methods for signalling sound end event, namely audio process can send a '''signal''' or can reply a '''message'''. Application specifies method choosen and its parameters by performing one of the two methods described below on ''audio.output'' object. Methods are usually called before the playback is started, but may be also called when object is already playing. The later solution is tricky however, as the sound may be very short, so a method may be called '''after''' the sound end. In this case signalling requests will be never triggered.

−	'''''MMM_SignalAtEnd()''''' method should be used, when we want to receive a signal to be Wait()-ed. It has two parameters, pointer to process to be signalled and signal number (not mask!) to be sent. We usually want to be signalled ourselves, but it is not a requirement, so process A can start playback, but signal may be received by process B.

−	''to be ~~continued~~...''	+	'''''MMM_SignalAtEnd()''''' method should be used, when we want to receive a signal to be Wait()-ed. It has two parameters, pointer to process to be signalled and signal number (not mask!) to be sent. We usually want to be signalled ourselves, but it is not a requirement, so process A can start playback, but signal may be received by process B. A typical usage may look like this:
		+
		+
		+	<tt>DoMethod(play, MMM_SignalAtEnd, FindTask(NULL), SIGBREAKB_CTRL_C);<br>
		+	DoMethod(play, MMM_Play);<br>
		+	Wait(SIGBREAKF_CTRL_C);</tt>
		+
		+
		+	In this code we send a request to be signalled themselves with system CTRL-C signal. It can be of course allocated private signal. Note that ''MMM_SignalAtEnd()'' method expect '''signal number''' while following ''Wait()'' needs a '''signal mask'''.
		+
		+	[http://krashan.ppa.pl/reggae/library/playaudio_signal.c A complete example source code using a signal]
		+
		+
		+	'''''MMM_ReplyMsgAtEnd()''''' signals the end of sound by sending a system message prepared by application to some message port set up by application as well. This method is useful especially when an application uses multiple sounds at once. Number of signals available to a process is very limited. Number of created messages is limited only by available memory. The method is also useful if application creates
		+	message port for other purposes. Then audio end messages can be directed to this port and distinguished by message contents. Typical usage looks as follows:
		+
		+
		+	<tt>struct MsgPort port; / created elsewhere */<br>
		+	struct Message msg; / allocated elsewhere */<br>
		+	<br>
		+	msg->mn_Node.ln_Type = NT_MESSAGE;<br>
		+	msg->mn_Length = sizeof(struct Message);<br>
		+	msg->mn_ReplyPort = port;<br>
		+	<br>
		+	DoMethod(play, MMM_Sound_ReplyMsgAtEnd, msg);<br>
		+	DoMethod(play, MMM_Play);<br>
		+	WaitPort(port);<br>
		+	GetMsg(port);</tt>
		+
		+
		+	The main difference between these two methods is that message signalling is "one-shot". After the message is sent to application's port, it must be got from the port and reinitialized before it can be reused again. Signal method may be used repeatedly, which is comfortable when a short sound is triggered multiple times.
		+
		+	[http://krashan.ppa.pl/reggae/library/playaudio_signal.c A complete example source code using a message]

@@ Line 53: / Line 53: @@
 *'''''MMM_Stop()''''' stops playback and rewinds the audio stream to the start (if possible).
-*'''''MMM_Pause()''''' (available since version 51.14 of ''audio.output'') stops playback, but does not rewind audio stream. Following ''MMM_Play'' will continue from paused position.
+*'''''MMM_Pause()''''' (available since version 51.14 of ''audio.output'') stops playback, but does not rewind audio stream. Following ''MMM_Play()'' will continue from paused position.
 All the methods are performed immediately, so just

@@ Line 47: / Line 47: @@
 ==Making noise==
-Playback is controlled with three methods: ''MMM_Play()'', ''MMM_Stop()'' and '' MMM_Pause'' performed on the ''audio.output'' instance.
+Playback is controlled with three methods: ''MMM_Play()'', ''MMM_Stop()'' and '' MMM_Pause()'' performed on the ''audio.output'' instance.
 *'''''MMM_Play()''''' starts playback if object is stopped, is ignored when object is playing.
@@ Line 67: / Line 67: @@
-stops it at any time. All methods are asynchronous to the caller and return immediately. Even if ''MMM_Play'' setup time is long (because of prebuffering for example), calling process is not stopped because setup is done by ''audio.output'' process.
+stops it at any time. All methods are asynchronous to the caller and return immediately. Even if ''MMM_Play()'' setup time is long (because of prebuffering for example), calling process is not stopped because setup is done by ''audio.output'' process.
 ==Waiting for end of sound==

← Older revision		Revision as of 18:31, 15 June 2010
Line 67:		Line 67:


−	stops it at any time. All methods are asynchronous to the caller and return immediately. Even if MMM_Play setup time is long (because of prebuffering for example), calling process is not stopped because setup is done by ''audio.output'' process.	+	stops it at any time. All methods are asynchronous to the caller and return immediately. Even if ''MMM_Play'' setup time is long (because of prebuffering for example), calling process is not stopped because setup is done by ''audio.output'' process.

	==Waiting for end of sound==		==Waiting for end of sound==