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, 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.
    1. 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.
    2. 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).
    3. 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.
    1. 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.
    2. 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.
    3. 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.
    4. 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.
    5. 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.
    6. 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.
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.

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.
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.
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:
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.
Example:
  • The following example shows how to destroy the AVChatManager instance.
    avChatMan.destroy();
    avChatMan = null;

getClip

public function getClip (
clipId:String) : Clip

Retrieve a Clip object instance from the clips list.
Parameters:
clipId:
(String) the id of the Clip object to be retrieved.
Returns:
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.
Events broadcasted to listeners:
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 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);
    }

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.
Returns:
  • A flash.net.NetStream object.
Throws:
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:

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.
Returns:
  • A flash.net.NetStream object already playing the previously recorded clip.
Throws:
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.
Parameters:
enableCamera :
enable video recording; default value is true.
enableMicrophone:
enable audio recording; default value is true.
Events broadcasted to listeners:
Throws:
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());
    }

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.
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.
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!
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.
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:
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
        ...
    }