How to use the VideoIO API?
The VideoIO application defines several properties, some of which are read-write to control the behavior, and others are read-only to indicate the status. When you embed VideoIO in your web page, you can statically set the values of the read-write properties using flashVars. You can also use JavaScript to set the values of these properties. Please see How to embed VideoIO in your web page? for details on these techniques. This section gives a complete reference on the VideoIO API.
The above link takes you to a demonstration and testing page of VideoIO. It embeds the VideoIO application, and displays all the properties using HTML controls. You can click on the property name to see more information about that property. For read-write properties, you can edit the value in place and see the behavior of the VideoIO application. For example, typing a value in the edit box and pressing "enter" causes the value to be assigned to that string or number property. Selecting or unselecting a checkbox causes the value to be assigned to that boolean property. The text area shows any useful trace information. Finally, you can right-click and view source code to understand how JavaScript is used to interact with the VideoIO application.
Properties
| Name | Type/default | Description |
| src | string | Represents the source URL of the VideoIO component, and controls the publish or playback mode. Allowed URL schemes are rtmp, rtmfp, http and https. The publish mode is allowed only with rtmp and rtmfp URLs. With rtmp and rtmfp URLs, additional URL parameter such as publish=stream1 or play=stream2 is used to specify the publish or play mode for the given stream name. Additionally, a record=true URL parameter causes the published stream to be recorded at the server as well. Thus, changing the src property can affect several other properties such as url, play, publish, live, and record. Setting src to null or "" stops any active publish or play mode. When setting via flashVars, do not set src property directly, but instead set url, play, publish and record explicitly. |
| poster | string | Represents the initial image to display before video is started to publish or play. This should be an http or https URL to a valid image resource. Setting poster to null or "" removes any initial image display. |
| preload | boolean, default false | Controls whether the video should be pre-loaded before it is played. This is useful only for play mode with http or https URL, where the video resource is pre-loaded hence can be played without interruption. |
| autoplay | boolean, default true | Controls whether the video should be played automatically when the src property is assigned and video is loaded, or should it wait for explicit play command using the playing property. This is useful only for play mode. |
| loop | boolean, default false | Controls whether the video should loop (rewind) to begining when it reaches the end, and start playing again. This is useful only for play mode, but not for live stream because live stream does not have an end time. |
| controls | boolean, default false | Controls whether the video control panel should be displayed or not. The VideoIO application displays a video control panel at the bottom of the user interface view. The control panel automatically hides if there is no mouse activity for some time, and the mouse is not over the control panel. If the mouse is rolled over the control panel, the control panel remains visible. Later, if the user moves the mouse anywhere on the video view, the control panel re-appears if it was hidden before. By default, a visible control panel displays various control buttons based on the current state. For example, if the play property is set, then the play/pause, speaker and volume controls are displayed, whereas if the publish property is set, then the record/stop, camera, microphone and gain controls are displayed. The video control panel allows the end user to control the behavior of the VideoIO application from within the Flash platform instead of having to build upon the JavaScript API. We recommend setting this to true for your application. |
| url | string | Represents the URL part of the src property. The url part excludes any parameters if the URL scheme is rtmp or rtmfp but includes those if the scheme is http or https. Although url is read-write, the application should not directly set this property using setProperty. Instead the application sets the src property, which implicitly sets the url. Setting the url property connects, disconnects or reconnects to the Flash media service in case of rtmp or rtmfp URLs, and starts load or unload of media resource in case of http or https URLs. When setting via flashVars you must set url and publish or play instead of setting src. |
| play | string | Represents the play stream name for streaming src value, such as rtmp or rtmfp URL. Although this is a read-write property the application should use the play parameter of the src property to set this. For example, if the src is set to "rtmp://server/path?play=live1" then the play property is automatically set to "live1". Setting this property also resets the publish and live properties and creates the media stream for the given play stream name. Resetting this property to null resets the playing property and stops the previous play stream if any. |
| publish | string | Represents the publish stream name for streaming src value, such as rtmp or rtmfp URL. Although this is a read-write property the application should use the publish parameter of the src property to set this. For example, if the src is set to "rtmp://server/path?publish=live1" then the publish property is automatically set to "live1". Setting this property also resets play and sets the live property, enables camera and microphone properties and creates the given publish stream name. Resetting this property to null resets the recording, live, camera and microphone properties and destroys the previous publish stream if any. |
| record | boolean, default false | Controls whether the publish stream is also recorded on the server, and is derived from the record parameter of the src property. For example if the src is set to "rtmp://server/path?publish=test1&record=true" then the record property is set to true. Changing this property in active publish mode changes the recording state at the server, and causes a re-publish of the media stream with new record value. |
| recordMode | string, default "record" | Controls whether the publish stream is also recorded by overwriting the previous recording (record) or by appending to the previous recording (append), and is derived from the recordMode parameter of the src property. For example if the src is set to "rtmp://server/path?publish=test1&recordMode=append" then the recordMode property is set to "append". When set in the src, it also implicitly sets record property to true. Changing recordMode property in active publish mode with record set, changes the overwrite versus append mode recording mode at the server, and causes a re-publish of the media stream with new recordMode value. |
| playMode | string, default "live" | Controls how the playing property affects the play stream and refers to whether the playing stream is downloaded from web, is live stream of a video-on-demand (vod) stream. It is derived from the src property as follows. If the src URL scheme is "http" or "https" then playMode is set to "web", otherwise if the playMode parameter of the src property is present that is used, otherwise it is set to default "live". For example if the src is set to "rtmp://server/path?play=test1&playMode=vod" then the playMode property is set to "vod". Setting this property is only allowed with "rtmp" or "rtmfp" URL scheme, and it can only be set to "vod" or "live" because "web" is implicitly used based on the URL scheme. The playMode controls how setting the playing property affects the stream. In the "web" mode, it calls the play() or pause() method of the VideoDisplay object, in the "vod" mode it calls the pause() or resume() method of the NetStream object for playing and in default "live" mode it creates or destroys the NetStream for playing. In some cases when you do not want to create or destroy the stream when the user clicks on the play/pause button, you should set playMode to "vod". Setting this property affects only the subsequent changes in the playing property. |
| live | boolean, default false | Controls whether the current display mode is live camera view or not. This is implicitly set when publish property is set. This can also be set by the live parameter in the src property. For example, when the src property is set to "?live=true" then live property is set to true. This property controls the camera property, but not vice-versa. This property when set also attaches the camera to the local video display. |
| playing | boolean, default false | Represents the play or pause state of the stream. Setting this property to true causes the media to start playing. For streaming media, it also creates the media stream with the Flash media server. Resetting this property to false stops any active playback. This property is implicitly set when autoplay is set and the src property is set to indicate a play mode using the play parameter. This property is also attached to the state of play/pause button in the control panel if visible. |
| recording | boolean, default false | Represents the publish or stop state of the stream. This is useful only for a publish stream of rtmp or rtmfp URL in src. Changing this property creates or destroys the media stream with the Flash media server. This property is implicitly set when src points to a publish stream, e.g., "rtmp://server/path?publish=live1, and the stream is created. This property is also attached to the state of the record/stop button in the control panel if visible. |
| privacyEvent | boolean, default false | (Deprecated in version 3.4+) Controls whether onShowingSettings callback function is called when the Flash Player settings is about to be displayed or hidden for device access. This is also useful if you wish to use the deviceAllowed property to know whether the device access is allowed or one. One use case is when you want to hide the audio-only Flash application under normal use but want to show it for settings display. |
| deviceAllowed | boolean, default false, read only | Represents whether device access is allowed by the end user for this application in the Flash Player settings. Please note that the Flash Player does not dispatch any event when the settings dialog box is closed, but does send an event when the user clicks on allow or deny radio buttons in the security panel box. |
| detectActivity | boolean, default true | Controls whether to detect mouse activity so that the control-bar, if present, can be automatically hidden after some inactivity. If you set this to false and set controls to true then the control-bar will not hide after mouse inactivity. |
| microphone | boolean, default false | Represents whether the microphone is on and capturing audio or not. This is implicitly set when publish property is set. This can be explicitly set to control the microphone on/off. This property is also attached to the microphone on/off icon on the control panel if visible. |
| codec | string, default "Speex" | Represents the microphone codec to use, and is "Speex" or "NellyMoser", as supported by Flash Player plugin. Setting the property also affects currently publishing audio stream. In Flash Player 11 or later, additional G.711 audio codecs are also available. You can set this property to "pcmu" or "pcma" to enable G.711 audio codec modes. |
| rate | number, default 16 | Represents the microphone sampling rate to use, and is 8 or 16. This is useful only when codec is "Speex". It represents the sampling rate of the audio codec in kHz. It is not recommended to change this value unless you really need to use a different sampling rate, e.g., for interoperating with telephony network you may need 8 kHz sampling. |
| encodeQuality | number, default 6 | Represents the microphone encode quality, and is a number between 0 and 10, with 10 indicating highest quality. This is useful only when codec is "Speex" and controls the bandwidth of the captured audio stream. |
| framesPerPacket | number, default 1 | Represents the microphone frames per packet, and is typically a small number like 1 or 2. It is not recommended to change this value. Some versions of Flash Player are known to work well when framesPerPacket is 1 if the codec is "Speex". |
| gain | number, default 0.5 | Represents the microphone gain, and is between 0 and 1, with 1 indicating maximum gain and 0 indicating mute. Since current version of Flash Player plugin does not have good acoustic echo cancellation, setting the gain to higher values causes lot of echo disturbance when used in multimedia call with speaker phone. This property is also attached to the microphone gain slider on the control panel if visible. |
| level | number, default 0, read-only | Indicates the microphone activity level, and is between 0 and 1. It is valid only when microphone is true and you are actively publishing a media stream indicating that the microphone is actively capturing the audio. This property is also attached to the microphone activity level on the control panel if visible. |
| echoSuppression | boolean, default true | Controls whether to enable or disable echo suppression on the underlying microphone object. |
| echoCancel | boolean, default true | Controls whether to enable or disable echo cancellation on the underlying microphone object when using Flash Player 10.3 or later. For earlier versions, it does not have any effect. If true it uses getEnhancedMicrophone with the default echo cancellation options, and if false it uses getMicrophone without echo cancellation options. Changing the property does not have any effect after microphone is set to true, which happens implicitly in publish mode. |
| sileneceLevel | number, default 0 | Represents the microphone silenece level for silence suppression, and is between 0 and 100, 0 indicating no silence suppression and 100 indicating suppress all audio. Recommended value is 2. |
| sound | boolean, default true | Controls whether the play sound is on or off. You can implement speaker mute mode by setting sound to false. This property is also attached to the speaker on/off icon on the control panel if visible. This controls the global sound volume of the application. |
| volume | number, default 0.5 | Represents the play sound volume between 0 and 1, with 1 indicating full volume. This property is also attached to the speaker volume slider on the control panel if visible. This controls the global sound volume of the application. |
| camera | boolean, default false | Represents whether the camera is on and capturing video or not. This is implicitly set when live or publish property is set. This can be explicitly set to control the camera on/off. This property is also attached to the camera on/off icon on the control panel if visible. On Mac OS, when set, it tries to use the "USB Video Class Video" camera, whereas on other platforms it tries to use the default camera. |
| cameraLoopback | boolean, default false | Controls whether a local view of what the camera is capturing is compressed and decompressed (true), as it would be for live transmission, or whether the local view is uncompressed (false). Enabling this property is useful to show the compressed video quality in local view, which otherwise shows only uncompressed video. Note that the local preview video is scaled to fit to the dimensions of VideoIO object. |
| cameraWidth | number, default 320 | (Deprecated in version 3.2+, see cameraDimension) Represents the camera capture width in pixels. By default we use 320x240 for all video dimension. Higher values give better quality picture but consume higher bandwidth. The application may want to increase the resolution of capture for higher quality recording. The aspect ratio is always 4:3, hence setting the cameraWidth also sets the cameraHeight accordingly. Note that the local preview video is scaled to fit to the dimensions of VideoIO object. |
| cameraHeight | number, default 240 | (Deprecated in version 3.2+, see cameraDimension) Represents the camera capture height in pixels. By default we use 320x240 for all video dimension. Higher values give better quality picture but consume higher bandwidth. The application may want to increase the resolution of capture for higher quality recording.The aspect ratio is always 4:3, hence setting the cameraHeight also sets the cameraWidth accordingly. |
| cameraFPS | number, default 12 | Controls the desired frames per second for the camera. Higher value gives better quality picture but consume higher bandwidth. The application may want to increase the frames per second for higher quality recording. Note however that this is just the desired value, and the actual value may be less than this based on other constraints such as maximum bandwidth available. Use currentFPS to know the actual frames per second. |
| keyFrameInterval | number, default 15 | Controls the desired key frame interval of the camera. The key or intra frame captures full image data instead of difference from previous or next frame. Key frames are useful to refresh the video when seeking or when there are packet loss on unreliable channel. Since Flash media streams run over reliable TCP transport, packet loss is not an issue unless gatewaying with some other system. A keyFrameInterval of 15 means that every 15th frame is a key frame. Allowed values are 1 to 28. We recommend not to change this value. |
| cameraQuality | number, default 0 | Controls the desired frame quality of the camera and is between 0 and 100. A value of 0 means the quality can vary as needed to avoid exceeding the available cameraBandwidth. A value of 1 means lowest quality with maximum compressions and 100 means highest quality without compression. For live video communication a value between 70-90 is ideal -- more than 90 consumes too much bandwidth, and less than 70 gives blocky picture quality. Ideally only one of cameraBandwidth or cameraQuality, but not both, should be set. |
| cameraBandwidth | number, default 0 | Controls the maximum bandwidth in bytes per second of the camera. A value of 0 means the camera can use as much bandwidth as needed to maintain the desired cameraQuality. Ideally only one of cameraBandwidth or cameraQuality, but not both, should be set. |
| videoCodec | string, default Sorenson, player 11+ only | Controls the video codec of the publishing NetStream attached to the camera when publish property is set. This property is only available when using Flash Player 11 or later, otherwise setting this property has no effect. There are two possible values, "Sorenson" or "H264Avc", for the default Sorenson codec or the new H.264 advanced video coding, respectively. Additionally for "H264Avc", profile and level can be supplied, e.g., "H264Avc/baseline/2" indicates baseline profile and level of 2. The possible values for profile are "baseline" and "main" and supported levels are 1, 1b, 1.1, 1.2, 1.3, 2, 2.1, 2.2, 3, 3.1, 3.2, 4, 4.1, 4.2, 5, and 5.1. Note that the videoCodec property is applied to the publishing stream for H.264 and not to the camera. Hence, if you enable cameraLoopback you will not see H.264 encoded video in your loopback view, but the remote party listening to this stream will receive H.264 encoded video. |
| videoWidth | number, default NaN, read-only | Represents the width in pixels of the active video display, if any, or NaN if none. This is the original unscaled width. The actual video display is scaled to fit the dimensions of VideoIO object. If the publish side sends a setVideoSize data then it is used to populate the videoWidth (and videoHeight) property. |
| videoHeight | number, default NaN, read-only | Represents the height in pixels of the active video display, if any, or NaN if none. This is the original unscaled height. The actual video display is scaled to fit the dimensions of VideoIO object. If the publish side sends a setVideoSize data then it is used to populate the videoHeight (and videoWidth) property. |
| currentFPS | number, default NaN, read-only | Represents the current frames per second of video display in live streaming mode. If unavailable, this is NaN. |
| display | boolean, default true | Controls whether video display is enabled or not, and applies to both publish and play mode. If you do not want to display the video, e.g., for audio-only user interface, or if you have multiple publish VideoIO instances, you can set this to false. |
| zoom | string, default "in" | Controls the zoom mode when the video aspect ratio is different than the display aspect ratio. The video aspect ratio is set by the capture device such as Camera, sent by the publishing stream to the playing stream or present in the video file itself. The display aspect ratio is determined by the dimension of the VideoIO.swf object and is based on the dimensions specified in embedding object or embed tags in HTML, SWFLoader component in parent SWF or monitor size in full screen mode. When this property is set to null, there is no zoom adjustiment made and the displayed video may be distorted, e.g., if 320x240 video is displayed in 1280x720 it will appear to be horizontally stretched. When this property is set to "in", the video is zoomed in without distortion so as to fill the full display size, e.g., if 320x240 video is displayed in 1280x720 it will zoom in central 320x180 of the video and fill the dull display area. When this property is set to "out", the video is zoomed out without distortion so as to show the full video, e.g., is 320x240 video is displayed in 1280x720 it will expand full 320x240 to central 960x720 region on the display area, but leave blank spaces on left and right side of the video. Default is "in" which is well suited for video conferencing. Allowed values are null, "in" and "out". If you have sub-titles or icon to be displayed on top or bottom, use null or "out" to display the full video because "in" can hide parts of the video on the sides. |
| mirrored | boolean, default true | Controls whether local view is mirrored or not. This does not apply to the play mode of remote view. This is useful if you want to avoid mirror view for local video. |
| smoothing | boolean, default true | Controls whether smoothing is applied to any video display or not. Since video smoothing algorithm consumes CPU cycles, applications may want to reset this property to reduce CPU utilization during play. The video smoothing removes pixelation effect on video if the video is scaled, e.g., the VideoIO dimension is different than actual video's width and height. |
| enableFullscreen | boolean, default true | This enableFullscreen property (note the case of "s") controls whether the full screen mode is enabled or not. If the full screen mode is disabled, then the user interface elements needed to do full screen are hidden. Resetting this property to false is useful if you know that full screen is not available, e.g., in Facebook FBML application. |
| enableFullscreen OnDoubleClick | boolean, default false | (Version 3.4+) This enableFullscreenOnDoubleClick property controls whether the full screen mode is toggled on double-click or not. This property is independent of enableFullscreen that controls the right-click context menu item. This new property is useful because of a bug in Flash Player that prevents the right-click context-menu to toggle the full screen mode when the video is displayed on top. This property provides an alternative work-around to that problem. When this property is set to true, you can double click on the video to toggle full screen mode. Note that double click has no effect if there is no video displayed, because the default background with alpha 0 does not detect the double-click event. |
| fullscreen | boolean, default false, read-only | Represents the full screen mode of the application. Due to restriction in Flash Player, this property can only be set in response to a mouse click or button press within Flash application. Hence setting this property by an external application has no effect. This property is also attached to the fullscreen button state in the control panel if visible, and the clicking the button toggles full screen mode. To allow full screen mode, the embedding HTML page must supply the allowFullScreen parameter as true in the object tag. |
| snapshot | string | Represents a one-time snapshot of the video stream as a Base64 encoded JPEG image data. Reading this property captures the current snapshot. You can set a previously captured snapshot to show that image. This property is useful in capturing the snapshot without the builtin control-bar button, e.g., to capture and send the image to some backend script. |
| group | string | Represents the group name of the application level multicast in both publish and play mode. This is implicitly set using the group parameter of the src property, e.g., when src is set to "rtmfp://server/path?group=my/group1&publish=live1" then the group property is automatically set to my/group1. This property must be set before publish or play so that it takes effect before publishing or playing. Note that the group feature is available only in Flash Player 10.1 or later, and you need appropriate VideoIO45.swf compiled using Flex SDK 4.5 or later. |
| objectEncoding | number, default 3 | Controls the connection's object encoding. Possible values are 3 or 0 for AMF3 or AMF0 respectively. This property must be set before src or url is set so that the value is applied before invoking the connect method on the underlying NetConnection. Setting it after the connection is initiated has no effect on the current connection. |
| proxyType | string, default "none" | Determines which fallback methods are tried if an initial connection attempt fails. Possible values are "none", "best", "HTTP" and "CONNECT". The value of "best" is particularly useful when using "rtmps" with native SSL instead of HTTPS tunneling. This property must be set before src or url is set so that the value is applied before invoking the connect method on the underlying NetConnection. Setting it after the connection is initiated has no effect on the current connection. |
| currentTime | number, default NaN | Represents the current play head position, in seconds, since the video started to play or record. For playback of live stream, the playhead position may start from some initial positive value if the player joins the stream after some time. If the current time is not known, the value is NaN. This property is also attached to the numeric display (as formatted duration in hh:mm:ss) on the control panel if available. Additionally, if duration is available, the currentTime controls the play head bar position on the control panel. Setting this property causes seek on media stream, if possible. |
| duration | number, default NaN | Represents the total length of the media, in seconds. For live or recorded streams, this value is unavailable or NaN. For real-time playback of the stream or downloaded video file, this value may not be available, unless set by metadata or video resource has finished playback once. If this is not available on the media stream or resource, but the application knows the duration out of band, it can set the property. This property is also attached to the length of the play head bar on the control panel if available. |
| bytesLoaded | number, default NaN, read-only | Indicates the number of bytes of data that have been loaded so far in the system. If unavailable, this is NaN. |
| bytesTotal | number, default NaN, read-only | Indicates the total size of the media resource being loaded in the system for play. If unavailable, such as for live streams, this is NaN. |
| quality | number, default 0, read-only | Indicates the quality of the play stream as a number between 0 (very low) and 1 (very high). The quality is calculated based on some combination of other metrics such as live delay of the stream. This property is also attached to the quality bars displayed in the control panel if available. In media stream play mode the control panel displays 4 quality bars indicating quality values in the range of (0, 0.25], (0.25, 0.5], (0.5, 0.75], (0.75, 1.0]), respectively. |
| bandwidth | number, default 0, read-only | Indicates the media stream bandwidth in bytes per second for live play or publish mode. It includes only the audio and video bandwidth of the stream. This property gives the rough idea of the bandwidth utilization. If unavailable, this is NaN. |
| bufferTime | number, default -1 | Controls the playing stream bufferTime in seconds. Default is negative (-1.0) which indicates do not set. If you are experiencing choppiness or jerkiness in the video display, set it to a higher value, especially for recorded video playback. This property only affects the play mode. |
| bufferTimeMax | number, default -1 | Controls the playing stream bufferTimeMax in seconds. Default is negative (-1.0) which indicates do not set. This property puts an upper limit on bufferTime. This property only affects the play mode. |
| bidirection | boolean, default false | Controls whether to allow media streams in both directions at the same time. This is applicable when setting play and publish properties. If bidirection is false, then setting play resets publish and vice-versa. |
| cameraDimension | string, default "320x240" | (version 3.2+) Controls the camera capture dimension. This property should be used instead of the cameraWidth or cameraHeight and is required when setting to a non-standard aspect ratio such as HD camera capture. When this property is changes, the cameraWidth and cameraHeight are also changed to reflect the new value. When the display size is not "320x240", it periodically transmits the publish dimension to the player using the NetStream's setVideoSize function, which in turn is used by the play side to adjust the aspect ratio of the display. |
| playerState | string, default null, read-only | (version 3.2+) Indicates the player state when playing a video using an http or https URL. For other play or publish modes such as using rtmp or rtmfp URLs, the value is null. Please see the VideoDisplay.state property in Adobe Flex documentation for details on the value of this playerState property. |
| liveDelay | number, default NaN, read-only | (version 3.2+) Indicates the play stream's live delay value in milliseconds. If this is unavailable (e.g., http playback) or not applicable (e.g., publish mode), it is set to NaN (not a number). This is useful in getting a rough idea on the quality of the play stream. In fact, the quality property for play stream uses this value to generate a quality number between 0 and 1. |
| multicastWindow Duration | number | (version 3.2+) This multicastWindowDuration is a mirror of the NetStream's multicastWindowDuration property and is useful in reducing the delay in group communication. |
| cameraNames | array, read-only | (version 3.4+) The list of names (string) of the cameras available in the system. It represents the Camera.names property of Flash Player. The Flash Player settings also displays this list under the camera tab. You may set any of the item from this list as the value of the cameraName property. |
| microphoneNames | array, read-only | (version 3.4+) The list of names (string) of the microphones available in the system. It represents the Microphone.names property of Flash Player. The Flash Player settings also displays this list under the microphone tab. You may set any of the item from this list as the value of the microphoneName property. |
| cameraName | string, default "default" | (version 3.4+) Controls the selected camera. When this is "default" then it uses the default device set in the end-user's system, and the end-user can select a different one on the Flash Player settings' camera tab. If this is set to any value from the cameraNames property, then the end-user cannot select a different device from the Flash Player settings for this instance. Hence, setting this property in your application is generally not recommended because a good application should let the end-user select the default device from the Flash Player settings. Setting the property to an invalid name will cause it to reset to "default" next time a camera object is created. Changing the device in the middle of a session is not supported, hence changing this property will not affect ongoing publish session. You should set this property only before setting any of publish, live or camera property. |
| microphoneName | string, default "default" | (version 3.4+) Controls the selected microphone. When this is "default" then it uses the default device set in the end-user's system, and the end-user can select a different one on the Flash Player settings' microphone tab. If this is set to any value from the microphoneNames property, then the end-user cannot select a different device from the Flash Player settings for this instance. Hence, setting this property in your application is generally not recommended because a good application should let the end-user select the default device from the Flash Player settings. Setting the property to an invalid name will cause it to reset to "default" next time a microphone object is created. Changing the device in the middle of a session is not supported, hence changing this property will not affect ongoing publish session. You should set this property only before setting any of publish, or camera property. |
Property access in JavaScript
The VideoIO embed defines several properties to control the behavior of the application or give indication of current status as described earlier. You can dynamically set or get these properties using JavaScript. First, you use getFlashMovie function to get the reference to your VideoIO object. Then you use getProperty and setProperty of the object, to get or set a property. Note that you need to delay the invocation of getFlashMovie, setProperty and getProperty until the Flash application is loaded to avoid any run-time exception. Calling these in response to user input works well in practice.
The following example shows a check box, which when selected will set the controls property of the VideoIO object named video1. Usually you should set autocomplete to "off" to avoid auto-completing these input controls by the browser when you refresh your page.
<object type="application/x-shockwave-flash" data="VideoIO.swf"
id="video1" width="320" height="240">
<param name="movie" value="VideoIO.swf" />
...
<param name="allowScriptAccess" value="always" />
</object>
<script>
function getFlashMovie(movieName) {
var isIE = navigator.appName.indexOf("Microsoft") != -1;
return (isIE) ? window[movieName] : document[movieName];
}
</script>
<input id="controls1" type="checkbox" autocomplete="off"
onclick="getFlashMovie('video1').setProperty('controls',
document.getElementById('controls1').checked)"/>
Following example shows an input text box which allows the user to enter a number, which gets get to the gain property of VideoIO object named video1.
<input id="gain1" type="text" style="width: 60px"
onkeypress="if ((event.keyCode || event.which) == 13) {
value = parseFloat(document.getElementById('gain1').value);
getFlashMovie('video1').setProperty('gain', value);
return false;
}"/>
The VideoIO application allows you to call any method on the back-end RTMP server using the Flash Player's connected NetConnection object. This is similar to setting/getting property as described before, except that you use callProperty method on the flash movie. The following example shows an input box which when entered invokes the "invite" method with the entered value as the first argument.
<input id="dest" type="text" style="width: 60px"
onkeypress="if ((event.keyCode || event.which) == 13) {
value = document.getElementById('dest').value;
getFlashMovie('video1').callProperty('call', 'invite', value);
return false;
}"/>
Actually, callProperty is a generic method which allows you to call any public method on the underlying VideoIO object. The "call" method is a public method on VideoIO object which uses NetConnection's call method to invoke a remote function on the server.
Additionally, we have added a new post method, to send some text message to the group communication. This is used in conjunction with group property described earlier. In particular, if VideoIO is used to publish a stream to a group, the application can also invoke post as follows. The second argument is the user name and the third is the text message.
getFlashMovie('video1').callProperty('post', 'my name', 'some message text');
On the receiving side, the onPostingNotify callback method is invoked as described later. The post method and onPostingNotify callback are useful for implementing multicast group communication, e.g., multiparty text chat. Note that similar to the group property, you need Flash Player version 10.1 or later and VideoIO45.swf compiled using Flex SDK 4.5 or later.
We have also added a new sendData method, to send some text message in a non-group communication, such as client-server RTMP or peer-to-peer RTMFP sessions. This method is used to send some text data in a publishing stream to all the other subscribed playing streams. This is particularly useful for P2P RTMFP mode using Stratus service where you cannot use the call method with server side chat feature, but you need an end-to-end text data transfer mechanism. Unlike the previous post method that works in a group, the sendData method is useful for client-server and peer-to-peer streams.
getFlashMovie('video1').callProperty('sendData', 'some text message');
The other end receives a onReceiveData callback as described later when it receives the text data in the stream. For a one-to-many stream, the publishers calls sendData and all the players receive onReceiveData callback. You can call sendData only if VideoIO is publishing, and will get onReceiveData only if VideoIO is playing. It is up to the application to define the meaning of the text data sent and received via this method.
Creation and change events
The VideoIO application invokes three JavaScript functions on certain events. These JavaScript functions, if defined, must be present in the global scope of the embedding HTML page. The onCreationComplete is invoked when the VideoIO application is created. The event parameter supplied to this function has an objectID property which you can use to identify the VideoIO object. The onPropertyChange is invoked when some property of the VideoIO application changes. The event parameter supplied to this function has objectID, property, oldValue and newValue properties. The property value stores the name of the property, e.g., "gain", which changed. The oldValue and newValue store the old and new value of that property during this change. The onCallback is invoked when the server invokes a client method on the NetConnection object. This is the reserve of the server method call, and allows the server to invoke a method on the client if needed. You may choose to ignore this method and not do anything.
Following example shows how you can get the initial value of controls and gain properties, and update the HTML input controls to indicate the initial values. It also shows how to update the input controls display everytime the property changes.
<script>
function onCreationComplete(event) {
var obj = getFlashMovie("video1");
document.getElementById("controls1").checked = obj.getProperty("controls");
document.getElementById("gain1").value = obj.getProperty("gain").toString();
}
function onPropertyChange(event) {
if (event.property == "controls")
document.getElementById("controls1").checked = event.newValue;
else if (event.property == "gain")
document.getElementById("gain1").value = event.newValue.toString();
}
function onCallback(event) {
if (event.method == "invited")
alert("you are getting invited: " + event.args);
}
</script>
We have added additional callbacks (or events) as follows. The onPostingNotify is invoked to notify any group posts to the application. Please see the post method for the meaning of user and text attributes of the event. The onReceiveData is invoked to indicate incoming text data in a playing stream. Please see the sendData method on how to send the data, which is available as the data attribute of the event in onReceiveData. The onShowingSettings is invoked to notify that the Flash Player security panel box is about to be shown.
This feature described in this paragraph has been deprecated in version 3.4 because our workaround of using the number of children no longer works in the latest version of Flash Player. Additionally, onShowingSettings is dispatched when the security panel box is closed. The showing boolean property in the event object is true if the settings box is about to be shown and false if it is hidden. We use a timer to periodically check whether the number of children on the stage has changed to determine when the settings box is closed. It is assumed that the application does not add or remove child object to the stage itself. The callback is invoked only when the privacyEvent property is set to true to indicate that the application is interested in receiving the privacy events using this callback. Please see the privacyEvent and deviceAllowed properties for details.
<script>
function onPostingNotify(event) {
log("onPostingNotify() user=" + event.user + ", text=" + event.text);
}
function onReceiveData(event) {
log("onReceiveData() data=" + event.data);
}
function onShowingSettings(event) {
log("onShowingSettings() showing=" + event.showing);
}
</script>
Documentation
For each property that is defined by VideoIO, it also defines a documentation text for that property which can help you know more about the property. For example, the __doc__gain property can be accessed to see the documentation on the gain property. Using the built-in API accessible documentation allows us to keep the documentation up-to-date with the actual implementation of various properties.
Following example shows a link which when clicked will display the documentation text for the gain property.
<script>
function help(name) {
var obj = getFlashMovie("video1");
alert(obj.getProperty("__doc__" + name).replace('\n', '<br/>'));
}
</script>
<a href="javascript:help('gain')">what is gain?</a>
You see view the source of the demonstration and testing page of VideoIO API to see these functions and many others in action.