AVClipManager
Kind of class: | public class |
---|---|
Package: | com.smartfoxserver.v2.redbox |
Inherits from: | BaseAVManager < EventDispatcher |
Version: | 1.0.0 for SmartFoxServer 2X |
Author: | The gotoAndPlay() Team http://www.smartfoxserver.com |
Classpath: | com.smartfoxserver.v2.redbox.AVClipManager |
File last modified: | Thursday, 05 May 2011, 10:29:33 |
SmartFoxServer 2X RedBox Audio/Video Clip Manager.
This class is responsible for audio/video clip recording & playback through the connection to the Red5 server.
The AVClipManager handles the list of available a/v clips, their custom additional properties and the streaming to/from the Red5 server.
NOTE: in the provided examples,
This class is responsible for audio/video clip recording & playback through the connection to the Red5 server.
The AVClipManager handles the list of available a/v clips, their custom additional properties and the streaming to/from the Red5 server.
NOTE: in the provided examples,
avClipMan
always indicates an AVClipManager instance.Usage:
- The AVClipManager class allows the playback of audio/video clips hosted on the server (for example movie trailers, video interviews, lessons, video messages, etc.) and the recording of live broadcasts.
Each clip can be described by a number of custom parameters that are saved on the file system together with the clip's flv file.
Videoclip player
In this kind of application, the list of available clips is retrieved and displayed on the stage. When the user clicks on an item, a video player handles the incoming stream. The following workflow is suggested.- The current user logs in and joins a Room (usually a lobby); the list of available clips is requested using the getClipList method.
Calling this method also enables the reception of the RedBoxClipEvent.CLIP_ADDED, RedBoxClipEvent.CLIP_DELETED and RedBoxClipEvent.CLIP_UPDATED events which notify that a new clip has been added or removed from the clips list, or that the properties of a clip have been updated. - The clips list is received by means of the RedBoxClipEvent.CLIP_LIST event: the clips, together with their properties (for example title, author, description, etc.) are listed in a specific component on the stage (for example a datagrid).
- When the user selects a clip, a NetStream object is requested to the AVClipManager by means of the getStream method and the playback is started using the clip's id with the NetStream's play method (a simple Video object or a more complex UI component with advanced seek/volume controls can be used to display the streaming clip).
Video message recorder
In this kind of application, a video message is recorded, previewed and finally submitted together with a number of additional properties. The following workflow is suggested.- The current user logs in and joins a Room (usually a lobby); the user interface displays the required controls to start/stop recording, preview a recorded clip, submit it or cancel the process; also, a form to collect the clip properties (for example the message title) is available.
- The user clicks on the "start recording" button: the startClipRecording method is invoked and a unique clip id is requested to the server-side extension.
- When the RedBoxClipEvent.CLIP_RECORDING_STARTED event is fired in response, the camera/microphone output is attached to an outgoing stream which is recorded on the file system by the Red5 server. A Video object is added to the stage to display the user's own camera output.
- The user clicks on the "stop recording" button: the stopClipRecording method is called and the outgoing stream is closed. The flv file on the server is now just temporary: if the user disconnects from SmartFoxServer or the cancelClipRecording method is called, the file is removed from the file system.
- The user clicks on the "preview clip" button: the previewRecordedClip method is called and a playing NetStream object is returned. The stream is attached to a Video object on the stage to display it.
- The user clicks on the "submit clip" button: the collected clip properties are passed to the submitRecordedClip method and saved on the server's file system together with the clip's flv file. On the server side the clip is added to the list of available clips.
- The current user logs in and joins a Room (usually a lobby); the list of available clips is requested using the getClipList method.
Events broadcasted to listeners:
- RedBoxClipEvent with type:
CLIP_LIST
- Dispatched when clips list is returned, in response to a getClipList request.
- RedBoxClipEvent with type:
CLIP_RECORDING_STARTED
- Dispatched when the recording af an a/v clip starts, in response to a startClipRecording request.
- RedBoxClipEvent with type:
CLIP_ADDED
- Dispatched when a new a/v clip has been submitted by one of the users in the current zone.
- RedBoxClipEvent with type:
CLIP_SUBMISSION_FAILED
- Dispatched when an error occurs in the RedBox server-side extension after submitting an a/v clip.
- RedBoxClipEvent with type:
CLIP_DELETED
- Dispatched when an a/v clip has been deleted by one of the users in the current zone.
- RedBoxClipEvent with type:
CLIP_UPDATED
- Dispatched when the properties of an a/v clip have been updated by one of the users in the current zone.
Summary
Constructor
- AVClipManager (sfs:SmartFox, red5Ip:String, useRTMPT:Boolean = false, debug:Boolean = false)
- AVClipManager contructor.
Instance properties
Instance properties inherited from BaseAVManager
Instance methods
- destroy : void
- Destroy the AVChatManager instance.
- getClipList : void
- Retrieve the list of available a/v clips for the current zone.
- getClip (clipId:String) : Clip
- Retrieve a Clip object instance from the clips list.
- getStream : NetStream
- Get a NetStream object which makes use of the AVClipManager connection to Red5.
- startClipRecording (enableCamera:Boolean = true, enableMicrophone:Boolean = true) : void
- Start recording a new a/v clip.
- stopClipRecording : void
- Stop current recording of an a/v clip.
- cancelClipRecording : void
- Cancel current recording of an a/v clip.
- previewRecordedClip : NetStream
- Preview the recorded a/v clip.
- submitRecordedClip (properties:Object = null) : void
- Submit the recorded a/v clip to the server.
- getRecordedClipId : String
- Get the id of the currently recorded clip.
- submitUploadedClip (clipId:String, properties:Object = null) : void
- Submit a previously uploaded a/v clip to the server.
- deleteClip (clipId:String) : void
- Remove a clip from the Red5 streams folder.
- updateClipProperties (clipId:String, properties:Object) : void
- Update the clip properties.
Instance methods inherited from BaseAVManager
Constructor
AVClipManager
public function AVClipManager (
sfs:SmartFox,
red5Ip:String,
useRTMPT:Boolean = false,
debug:Boolean = false)
AVClipManager contructor.
Parameters:
sfs :
the SmartFox API main class instance.
red5Ip :
the Red5 server IP address (include the port number if the default one is not used).
useRTMPT:
connect to Red5 server using the HTTP-tunnelled RTMP protocol (optional, default is
false
); Red5 must be configured accordingly.debug :
turn on the debug messages (optional, default is
false
).Example:
- The following example shows how to instantiate the AVClipManager class.
var smartFox:SmartFox = new SmartFox(); var red5IpAddress:String = "127.0.0.1"; var avClipMan:AVClipManager = new AVClipManager(smartFox, red5IpAddress);
Instance methods
cancelClipRecording
public function cancelClipRecording (
) : void
Cancel current recording of an a/v clip.
This method stops the current a/v clip recording (if not already stopped by means of the stopClipRecording method) and forces the temporary clip created on the server to be deleted immediately.
This method stops the current a/v clip recording (if not already stopped by means of the stopClipRecording method) and forces the temporary clip created on the server to be deleted immediately.
Example:
- The following example shows how to cancel a clip recording.
avClipMan.cancelClipRecording(); // Detach camera output from video instance on the stage video.attachCamera(null);
deleteClip
public function deleteClip (
clipId:String) : void
Remove a clip from the Red5 streams folder.
In order to delete a clip, the user must be the its owner (see the Clip.username property).
If the clip is deleted successfully, the AVClipManager's internal clips list is updated and the RedBoxClipEvent.CLIP_DELETED event is fired.
In order to delete a clip, the user must be the its owner (see the Clip.username property).
If the clip is deleted successfully, the AVClipManager's internal clips list is updated and the RedBoxClipEvent.CLIP_DELETED event is fired.
Parameters:
clipId:
the id of the clip to be deleted.
Events broadcasted to listeners:
- RedBoxClipEvent with type:
CLIP_DELETED
- Dispatched when an a/v clip has been deleted by one of the users in the current zone.
Throws:
- ClipActionNotAllowedException if the user is not the clip's owner.
Example:
- The following example shows how to delete a clip.
avClipMan.addEventListener(RedBoxClipEvent.CLIP_DELETED, onClipDeleted); avClipMan.deleteClip(clipId); function onClipDeleted(evt:RedBoxClipEvent):void { trace("The clip " + evt.params.clip.id + " was deleted"); }
destroy
override public function destroy (
) : void
Destroy the AVChatManager instance.
Calling this method causes the interruption of all chat sessions currently in progress (if any) and the disconnection from Red5.
This method should always be called before deleting the AVChatManager instance.
Calling this method causes the interruption of all chat sessions currently in progress (if any) and the disconnection from Red5.
This method should always be called before deleting the AVChatManager instance.
Example:
- The following example shows how to destroy the AVChatManager instance.
avChatMan.destroy(); avChatMan = null;
Overrides:
getClip
Retrieve a Clip object instance from the clips list.
Parameters:
clipId:
(String) the id of the Clip object to be retrieved.
Returns:
- The Clip object.
Example:
- The following example shows how to get a clip from the clips list.
var clip:Clip = avClipMan.getClip(clipId); if (clip != null) { trace ("Clip id:", clip.id); trace ("Clip submitter:", clip.username); trace ("Clip size:", clip.size + " bytes"); trace ("Clip last modified date:", clip.lastModified); trace ("Clip properties:"); for (var s:String in clip.properties) trace (s, "-->", clip.properties[s]); }
See also:
getClipList
public function getClipList (
) : void
Retrieve the list of available a/v clips for the current zone.
The clip list is requested to the RedBox server-side extension only the first time that this method is called, then only updates are notified.
The list is an array of Clip objects returned by means of the RedBoxClipEvent.CLIP_LIST event.
The clip list is requested to the RedBox server-side extension only the first time that this method is called, then only updates are notified.
The list is an array of Clip objects returned by means of the RedBoxClipEvent.CLIP_LIST event.
Events broadcasted to listeners:
- RedBoxClipEvent with type:
CLIP_LIST
- Dispatched when clips list is returned, in response to a getClipList request.
Example:
- The following example shows how to request the clips list to the AVClipManager instance.
avClipMan.addEventListener(RedBoxClipEvent.CLIP_LIST, onClipList); avClipMan.getClipList(); function onClipList(evt:RedBoxClipEvent):void { for each (var clip:Clip in evt.params.clipList) { trace ("Clip id:", clip.id); trace ("Clip submitter:", clip.username); trace ("Clip size:", clip.size + " bytes"); trace ("Clip last modified date:", clip.lastModified); trace ("Clip properties:"); for (var s:String in clip.properties) trace (s, "-->", clip.properties[s]); } }
getRecordedClipId
public function getRecordedClipId (
) : String
Get the id of the currently recorded clip.
This id is
The recorded clip id is usually not necessary, unless a more advanced control over the clip preview is required with respect to what the previewRecordedClip method offers.
In this case the getStream method can be used and the clip stream played by means of its id.
This id is
null
until the RedBoxClipEvent.CLIP_RECORDING_STARTED event is received, and it's set back to null
when the submitRecordedClip or cancelClipRecording methods are called.The recorded clip id is usually not necessary, unless a more advanced control over the clip preview is required with respect to what the previewRecordedClip method offers.
In this case the getStream method can be used and the clip stream played by means of its id.
Returns:
- The id of the recorded clip.
Example:
- The following example shows how to use the id to preview a recorded a/v clip.
var recordedClipId:String = avClipman.getRecordedClipId(); var stream:NetStream = avClipMan.getStream(); stream.client = this; // This is required in order to handle the onPlayStatus event. video.attachNetStream(stream); // Attach stream to a Video object instance on the stage to preview the recorded clip stream.play(recordedClipId, 0); function onPlayStatus(info:Object):void { // Reset video upon completion if (info.code == "NetStream.Play.Complete") video.attachNetStream(null); }
See also:
getStream
public function getStream (
) : NetStream
Get a NetStream object which makes use of the AVClipManager connection to Red5.
This method can be used to retrieve a valid NetStream object and play an a/v clip from the clips list by means of its id.
This method can be used to retrieve a valid NetStream object and play an a/v clip from the clips list by means of its id.
Returns:
- A flash.net.NetStream object.
Throws:
- NoAVConnectionException if the connection to Red5 is not available.
Example:
- The following example shows how to get a stream and play a clip; the "onMetaData" handler is also set to trace the clip's flv metadata.
var stream:NetStream = avClipMan.getStream(); stream.client = this; // This is required in order to handle the onMetaData, onCuePoint and onPlayStatus events. // Check the flash.net.NetStream class documentation for more details. video.attachNetStream(stream); // Attach stream to a Video object instance on the stage stream.play(clipId, 0); function onMetaData(info:Object):void { trace ("Duration: " + info.duration); trace ("Framerate: " + info.framerate); trace ("Width: " + info.width); trace ("Height: " + info.height); }
See also:
- NoAVConnectionException
- flash.net.NetStream
previewRecordedClip
public function previewRecordedClip (
) : NetStream
Preview the recorded a/v clip.
This method stops the current a/v clip recording (if not already stopped by means of the stopClipRecording method) and plays it back for preview purposes.
The returned flash.net.NetStream object is already playing and clip events can't be catched. For a more advanced control over the clip preview, check the getRecordedClipId method.
This method stops the current a/v clip recording (if not already stopped by means of the stopClipRecording method) and plays it back for preview purposes.
The returned flash.net.NetStream object is already playing and clip events can't be catched. For a more advanced control over the clip preview, check the getRecordedClipId method.
Returns:
- A flash.net.NetStream object already playing the previously recorded clip.
Throws:
- NoAVConnectionException if the connection to Red5 is not available.
Example:
- The following example shows how to preview a recorded clip.
var stream:NetStream = avClipMan.previewRecordedClip(); // Attach stream to a Video object instance on the stage to display the preview video.attachNetStream(stream);
startClipRecording
public function startClipRecording (
enableCamera:Boolean = true,
enableMicrophone:Boolean = true) : void
Start recording a new a/v clip.
When this method is called, a unique clip id is requested to the RedBox server-side extension (unless a previous one is already available).
On extension response, the recording is started and the RedBoxClipEvent.CLIP_RECORDING_STARTED event is fired.
Audio and video recording mode/quality should be set before calling this method. In order to alter these settings, please refer to the flash.media.Microphone and flash.media.Camera classes documentation.
When this method is called, a unique clip id is requested to the RedBox server-side extension (unless a previous one is already available).
On extension response, the recording is started and the RedBoxClipEvent.CLIP_RECORDING_STARTED event is fired.
Audio and video recording mode/quality should be set before calling this method. In order to alter these settings, please refer to the flash.media.Microphone and flash.media.Camera classes documentation.
Parameters:
enableCamera :
enable video recording; default value is
true
.enableMicrophone:
enable audio recording; default value is
true
.Events broadcasted to listeners:
- RedBoxClipEvent with type:
CLIP_RECORDING_STARTED
- Dispatched when the recording af an a/v clip starts, in response to a startClipRecording request.
Throws:
- NoAVConnectionException if the connection to Red5 is not available.
- InvalidParamsException if both enableCamera and enableMicrophone parameters are set to
false
.
Example:
- The following example shows how to start recording a new clip; camera mode is set before starting the recording.
avClipMan.addEventListener(RedBoxClipEvent.CLIP_RECORDING_STARTED, onClipRecordingStarted); try { var camera:Camera = Camera.getCamera(); camera.setMode(320, 240, 15); avClipMan.startClipRecording(true, true); } catch (err:NoAVConnectionException) { trace (err.message); } function onClipRecordingStarted(evt:RedBoxClipEvent):void { // Attach camera output to video instance on stage to see what I'm recording video.attachCamera(Camera.getCamera()); }
See also:
- stopClipRecording
- cancelClipRecording
- previewRecordedClip
- submitRecordedClip
- RedBoxClipEvent.CLIP_RECORDING_STARTED
- NoAVConnectionException
- InvalidParamsException
- flash.media.Camera
- flash.media.Microphone
stopClipRecording
public function stopClipRecording (
) : void
Stop current recording of an a/v clip.
This method stops the current a/v clip recording started with the startClipRecording method.
When a recording is stopped, the resulting clip is still temporary and must be saved by calling the submitRecordedClip method.
If a clip is not submitted, the temporary file on the server is deleted when the cancelClipRecording method is called or when the user disconnects from SmartFoxServer.
This method stops the current a/v clip recording started with the startClipRecording method.
When a recording is stopped, the resulting clip is still temporary and must be saved by calling the submitRecordedClip method.
If a clip is not submitted, the temporary file on the server is deleted when the cancelClipRecording method is called or when the user disconnects from SmartFoxServer.
Example:
- The following example shows how to stop clip recording.
avClipMan.stopClipRecording(); // Detach camera output from video instance on the stage video.attachCamera(null);
submitRecordedClip
public function submitRecordedClip (
properties:Object = null) : void
Submit the recorded a/v clip to the server.
This method stops the current a/v clip recording (if not already stopped by means of the stopClipRecording method) and makes the RedBox server-side extension save the clip properties and add it to the clips list.
If the submission is successful, the RedBoxClipEvent.CLIP_ADDED event is fired, otherwise the RedBoxClipEvent.CLIP_SUBMISSION_FAILED event is fired.
This method stops the current a/v clip recording (if not already stopped by means of the stopClipRecording method) and makes the RedBox server-side extension save the clip properties and add it to the clips list.
If the submission is successful, the RedBoxClipEvent.CLIP_ADDED event is fired, otherwise the RedBoxClipEvent.CLIP_SUBMISSION_FAILED event is fired.
Parameters:
properties:
an object containing the clip properties (see the Clip.properties attribute) to be saved. Only properties of type
String
, Number
and Boolean
are accepted; also, Number
and Boolean
are converted to String
.Events broadcasted to listeners:
- RedBoxClipEvent with type:
CLIP_ADDED
- Dispatched when a new a/v clip has been submitted by one of the users in the current zone.
- RedBoxClipEvent with type:
CLIP_SUBMISSION_FAILED
- Dispatched when an error occurs in the RedBox server-side extension after submitting an a/v clip.
Example:
- The following example shows how to submit a recorded clip.
avClipMan.addEventListener(RedBoxClipEvent.CLIP_ADDED, onClipAdded); var clipProperties:Object = {}; clipProperties.title = "My first video message"; clipProperties.author = "jack"; avClipMan.submitRecordedClip(clipProperties); function onClipAdded(evt:RedBoxClipEvent):void { trace("A new clip was added"); var clip:Clip = evt.params.clip; // Update the clip list ... }
submitUploadedClip
public function submitUploadedClip (
clipId:String,
properties:Object = null) : void
Submit a previously uploaded a/v clip to the server.
This method should be used when a new clip has been uploaded to the Red5 streams folder directly, for example via FTP (instead of being recorded using the startClipRecording method).
By submitting the clip, the RedBox server-side extension saves the passed properties and causes the RedBoxClipEvent.CLIP_ADDED event to be triggered to notify the clips list update to all users.
If the submission fails, the RedBoxClipEvent.CLIP_SUBMISSION_FAILED event is fired.
NOTE: the file extension of the uploaded clip must be lowercase!
This method should be used when a new clip has been uploaded to the Red5 streams folder directly, for example via FTP (instead of being recorded using the startClipRecording method).
By submitting the clip, the RedBox server-side extension saves the passed properties and causes the RedBoxClipEvent.CLIP_ADDED event to be triggered to notify the clips list update to all users.
If the submission fails, the RedBoxClipEvent.CLIP_SUBMISSION_FAILED event is fired.
NOTE: the file extension of the uploaded clip must be lowercase!
Parameters:
clipId :
the id of the uploaded clip. The id must match the flv file name, extension excluded; also, the clip id must begin with the zone name followed by an underscore character.
properties:
an object containing the clip properties (see the Clip.properties attribute) to be saved. Only properties of type
String
, Number
and Boolean
are accepted; also, Number
and Boolean
are converted to String
.Events broadcasted to listeners:
- RedBoxClipEvent with type:
CLIP_ADDED
- Dispatched when a new a/v clip has been submitted by one of the users in the current zone.
- RedBoxClipEvent with type:
CLIP_SUBMISSION_FAILED
- Dispatched when an error occurs in the RedBox server-side extension after submitting an a/v clip.
Example:
- The following example shows how to submit "VideoClipPlayer_TheDarkKnight.flv" videoclip, previously uploaded to the Red5 streams folder.
avClipMan.addEventListener(RedBoxClipEvent.CLIP_ADDED, onClipAdded); var clipProperties:Object = {}; clipProperties.title = "The Dark Knight"; clipProperties.author = "Warner Bros."; avClipMan.submitUploadedClip("VideoClipPlayer_TheDarkKnight", clipProperties); function onClipAdded(evt:RedBoxClipEvent):void { trace("A new movie trailer was added!"); var clip:Clip = evt.params.clip; // Update the clip list ... }
updateClipProperties
public function updateClipProperties (
clipId:String,
properties:Object) : void
Update the clip properties.
In order to update the clip properties, the user must be the clip's owner (see the Clip.username property).
If the clip properties are updated successfully, the AVClipManager's internal clips list is updated and the RedBoxClipEvent.CLIP_UPDATED event is fired.
NOTE: it's not possible to update a subset of properties, leaving the remaining ones unaltered: when this method is called, the whole clip's properties file is overwritten.
In order to update the clip properties, the user must be the clip's owner (see the Clip.username property).
If the clip properties are updated successfully, the AVClipManager's internal clips list is updated and the RedBoxClipEvent.CLIP_UPDATED event is fired.
NOTE: it's not possible to update a subset of properties, leaving the remaining ones unaltered: when this method is called, the whole clip's properties file is overwritten.
Parameters:
clipId :
the id of the clip to update.
properties:
an object containing the clip properties (see the Clip.properties attribute) to be saved. Only properties of type
String
, Number
and Boolean
are accepted; also, Number
and Boolean
are converted to String
.Events broadcasted to listeners:
- RedBoxClipEvent with type:
CLIP_UPDATED
- Dispatched when the properties of an a/v clip have been updated by one of the users in the current zone.
Throws:
- ClipActionNotAllowedException if the user is not the clip's owner.
Example:
- The following example shows how to update the properties of a clip.
avClipMan.addEventListener(RedBoxClipEvent.CLIP_UPDATED, onClipUpdated); var newClipProperties:Object = {}; newClipProperties.title = "Batman - The Dark Knight"; newClipProperties.author = "Warner Bros."; avClipMan.updateClipProperties(clipId, newClipProperties); function onClipUpdated(evt:RedBoxClipEvent):void { trace("Clip properties have been updated"); var clip:Clip = evt.params.clip; // Update the clip list ... }