The UMSCapture object provides methods to capture video from a video device and audio from an audio device, and interleave video/audio chunks in a fast file format. After capture completion, the save method converts the captured data into an AVI format file.
To learn more about the UMSCapture object, see:
For introductory information, see Movie Capture and Playback Objects.
To avoid name collision on defines, integer values have been captured as enumerated lists. The set of valid values from an enumerated list can vary with the application. The method descriptions detail valid or possible values for the specific use. The enumerated lists that are defined for this object are listed below:
enum ReturnCode {
Success,
NoFile,
NoFileObj,
NoConfigObj,
NoAlias,
NoDevice,
DeviceNotReady,
InvalidState,
WrongFormat,
WrongMode,
OutOfRange,
FileError,
InvalidFactor,
InvalidCommand,
NoWindow,
ColorMap,
Unknown,
InvalidParam,
Uninitialized,
TempNotSaved,
ValueChanged,
WindowDefined,
NotSupport,
NoEventPending,
MemoryError,
Failure,
AudioNotAvail,
VideoNotAvail
};
enum OnOff {
Off,
On
};
enum EventType {
Error,
RecordComplete,
SaveComplete
}
enum StateType {
NotReadyState,
ReadyState,
RecordState,
PauseState,
SaveState,
PendingState
};
enum ErrorType {
AudioDeviceError,
VideoDeviceError,
FileIOError
};
The capture object has the following possible states:
*The state might not be changed; it depends on whether the audio device is required for the capture. If audio_capture has been set ON, an open video and an open audio is required to enter ready state.
+Might be in NotReady state; depends on whether the required device for record is available.
If the above methods don't change the state UMSCapture object returns an InvalidState or Ignore return code.
This method uses an alias to specify which video device should be used for the Capture. The configuration persistent object is accessed to relate the alias to a device name.
Note: For some video devices, the alias is ignored.
| in string alias | The video device alias specifying the desired video device. Device aliases are mapped in the configuration file to real devices. This allows you to map applications to devices and establish device characteristics independently for each application if desired. Applications should use a device alias of the form:
Video.<application_class>.<application_name>.<usage_of_device> |
In the alias search this name is successively truncated until a match in the configuration file is found. If you have not specially identified any of the intermediate aliases the search resolves to the base Video alias.
| NoConfigObj | The configuration file does not exist. |
| NoAlias | The alias name does not exist in the configuration file. |
| NoDevice | The device specified in the configuration file does not exist. |
| DeviceNotReady | The device is not available. |
This method sets the dimensions of the image coming from the analog source. This applies to compressed images. The valid sizes are analog video format specific.
This method returns Success if width and height are valid. Otherwise, the closest valid width and height is set, and ValueChanged is returned.
The default image size is 320x240 for NTSC and 384x288 for PAL.
| inout long width | This is the width of input image. |
| inout long height | This is the height of input image. |
| DeviceNotReady | Video device has not been opened. |
| ValueChanged | Setting changed to closest height and width. |
This method allows the application to query the dimensions of the image size.
| inout long width | The current setting of the width of input image is returned. |
| inout long height | The current setting of the height of input image is returned. |
| DeviceNotReady | Video device has not been opened. |
This method sets the format of the output image for the AIXwindows window. If the format is unsupported, NotSupport is returned. For any other error, Failure is returned. The default format is RGB8Dither.
| in string image_format | The string specifies the desired format. The possible values of the format are RGB8Dither and RGB24 (a 24-bit graphics adapter is needed). |
| NotSupport | The image format is not a supported format. |
This method returns current monitor image format setting.
| out string image_format | The string value representing the current format setting for monitor image. The possible values of the format are RGB8Dither and RGB24. |
| DeviceNotReady | Video device has not been opened. |
This method sets the video format. The valid values for the format are NTSC and PAL. If the format is unsupported, NotSupport is returned. For any other errors, Failure is returned. The default format is NTSC.
| in string image_format | The string specifies the video format. |
| NotSupport | The image format is not a supported format. |
This method returns video format setting as a string value.
| out string image_format | A string containing the video format is returned. The possible values of the format are NTSC and PAL. |
| DeviceNotReady | Video device has not been opened. |
This method allows the application to set the number of frames per second to be captured. The video device supports certain capture rates. This method returns Success if the capture rate is valid. Otherwise, the closest valid rate is set and a ValueChanged return code is returned. The default rate is 15.
| inout float rate | Specifies number of frames per second to capture. |
| DeviceNotReady | Video device has not been opened. |
| ValueChanged | The setting has been changed. |
This method returns current capture rate in frames per second.
| inout float rate | The current capture rate in frames per second. |
| DeviceNotReady | Video device has not been opened. |
This method sets quality factor for JPEG compression. The range of quality factor is between 1 and 100. The higher factor gets the better quality image and a larger compressed JPEG file. If the factor is not valid, the closest valid factor is set and ValueChanged return code is returned. The default quality factor is 80.
| inout long factor | A value specifying the desired quality factor. |
| DeviceNotReady | Video device has not been opened. |
| ValueChanged | The setting has been changed. |
This method returns the current quality factor setting.
inout long factor The current quality factor setting.
| DeviceNotReady | Video device has not been opened. |
This method sets the window ID created by the application for monitoring input video from the video device. The video device has to be opened before set_window. The application has to set window ID before video monitoring is enabled.
| in string display | Specifies the display name the window is connected to. |
| in long window_id | Specifies the window ID for monitoring. |
| WindowDefined | Window has been set. Use release_window. |
This method returns the current window ID setting for monitoring input video.
| out string display | Returns the current display name. |
| inout long window_id | The current window ID for monitoring input video. |
This method releases the window ID for monitoring input video. The application can now reset the monitor window.
This method allows the application to turn on/off monitoring input video to the AIXwindows window. The default value is Off.
| in OnOff flag | The flag specifies monitoring on or off. |
This method returns the current window_monitor_flag setting.
| inout OnOff flag | The current setting is returned, possible values are On and Off. |
This method allows the application to turn on/off monitoring of input video on the analog video out monitor. The default value of this flag is On.
| in OnOff flag | The flag specifies monitoring on or off. |
This method returns the current video_out_monitor_flag setting.
| inout OnOff flag | The current setting is returned, possible values are On and Off. |
This method allows the application to turn on/off monitoring of input audio. The default value of the audio monitor flag is Off.
| in OnOff flag | The flag specifies monitoring On or Off |
This method returns the current audio_monitor_flag setting.
| inout OnOff flag | The current setting is returned, possible values are On and Off. |
This method allows the application to select whether to capture input audio when recording. The default value of the audio_capture_flag is On.
| in OnOff flag | The flag specifies capturing on or off |
This method returns the current audio_capture_flag setting.
| inout OnOff flag | The current setting is returned, possible values are On and Off. |
This method uses an alias to specify which audio device should be used by the Capture object. The configuration persistent object is accessed to relate the alias to a device name.
| in string alias | The audio device alias specifying the desired audio device. Device aliases are mapped in the configuration file to real devices. This allows you to map applications to devices and establish device characteristics independently for each application if desired. Applications should use a device alias of the form:
Audio.<application_class>.<application_name>.<usage_of_device> In the alias search this name is successively truncated until a match in the configuration file is found. If you have not specially identified any of the intermediate aliases the search resolves to the base Audio alias. |
This method closes the previously opened audio device.
This method closes the previously opened video device.
This method starts capturing video and audio data (if the capture audio flag is On). The captured video and audio chunks are saved in a temporary fast file. The configuration file alias, fast_file_path, specifies the name of the temporary fast file.
This method pauses the video (and audio) recording. The devices and fast file are still open. Record can be continued by the resume or record method.
This method resumes the recording of video (and audio) data when it has been paused.
This method stops the video (and audio) recording and closes the temporary fast file, no more data can be appended to this file. Once stopped, the capture object is in the pending state. The application can either save the file or select new to erase the current recording.
This method converts the temporary fast file to AVI format and saves it. The method executes asynchronously, returning success if the parameters are valid. The application is notified by a SaveComplete event when the save is complete.
| in string path | Specifies the pathname of the file to save. |
| in long fmode | Specifies the permissions for the file is being saved. This value is ignored if the file already exists. |
This method throws away the data in the current temporary file. Parameter values remain in their previously set state.
This method provides a way to stop the saving of a file.
This method sets the quantization tables for the JPEG compression of the video device. Each table should be 64 bytes long. The valid table ID strings are QTABLE_A_Y, QTABLE_A_C, QTABLE_B_Y, and QTABLE_B_C.
| in string tableid | Specifies the quantization table ID. |
| in sequence <octet> table | This is a sequence of octets used as a buffer which contains the 64 bytes of quantization table data to be updated. |
This method allows applications to query the quantization tables for the JPEG compression of the video device. Each table is 64 bytes long. The valid table ID are QTABLE_A_Y, QTABLE_A_C, QTABLE_B_Y and QTABLE_B_C.
| in string tableid | Specifies the quantization table ID. |
| inout sequence <octet> table | This is a sequence of octets used as a buffer which holds the 64 byte quantization table data being returned. |
This method sets the Huffman table for JPEG compression. The possible values of tableid are HUFFMANYDC, HUFFMANYAC, HUFFMANCDC, and HUFFMANCAC.
| in string tableid | A string specifying the Huffman table ID. |
| in sequence <octet> table | This is a sequence of octets used as a buffer which contains the Huffman table data being specified. |
| in long table_size | Use the table_size parameter to specify the size of the current Huffman table. |
This method returns the current Huffman table for the video device. The possible values of tableid are HUFFMANYDC, HUFFMANYAC, HUFFMANCDC, and HUFFMANCAC.
| in string tableid | A string specifying the Huffman table ID. |
| inout sequence <octet> table | This is a sequence of octets used as a buffer which holds the Huffman table data being returned. |
| inout long table_size | Returns the size of the current Huffman table. |
This method allows a sub-image within an image to be compressed. This method does not need to be called if the full image is to be compressed. The offsets must be positive integer values, less than or equal to the values used by set_input_image_size.
| inout long x_position | Specifies the offset, within the input image, to begin compressing in the x direction. The default value is 0. |
| inout long y_position | Specifies the offset, within the input image, to begin compressing in the y direction. The default value is 0. |
| inout long width | Specifies the number of pixels in x direction to compress. The default value is the same value as in set_input_image_size. |
| inout long height | Specifies the number of pixels in y direction to compress. The default value is the same value as in set_input_image_size. |
This method returns the current subimage settings.
| inout long x_position | Returns the offset, within the input image, to begin compressing in the x direction. |
| inout long y_position | Returns the offset, within the input image, to begin compressing in the y direction. |
| inout long width | Returns the number of pixels in x being compressed. |
| inout long height | Returns the number of pixels in y being compressed. |
This method allows you to set the values in the colormap for the video monitoring window, if you do not want to use the default color map provided by Capture object, which is 128 entries starting from index 128. The values for the size and the starting index comes from the set_colormap_index and set_colormap_size methods. The colormap is attached to the monitoring window.
| in sequence <octet> color_map | This is a sequence of octets used as a buffer which contains the color lookup table being specified. The data have to be in this format:
0, R, G, B, 0, R, G, B, ..., 0, R, G, B. \_______/ \_______/ \_______/ | | | Entry 0 Entry 1 .... Entry (n - 1) Where each entry is a 32-bit record containing 8-bit color lookup values. |
This method returns the current colormap settings.
| inout sequence <octet> colormap | This is a sequence of octets used as a buffer which holds the colormap data being returned. The colors are formatted as:
, R, G, B, 0, R, G, B, ..., 0, R, G, B. \_______/ \_______/ \_______/ | | | Entry 0 Entry 1 .... Entry (n - 1) Where each entry is a 32-bit record containing 8-bit color lookup values. |
This method allows the application to query the color map ID of the current monitoring window.
| inout long cmap_id | Returns the current colormap ID. |
This method sets the base index of color map for the monitoring window to use. The default base index is 128. It returns Success if the index is valid. Otherwise the closest valid index is set and ValueChanged is returned.
| inout long index | Specifies the desired base index. |
This method returns the base index of color map for the monitoring window is using.
| inout long index | Returns the current base index. |
This method sets the size of color map for the monitoring window to use. The default size is 128. It returns Success if the size is valid. Otherwise the closest valid size is set and a ValueChanged return code is returned.
| inout long size | Specifies the desired size. |
This method returns the current size of color map for monitoring window is using.
| inout long size | Returns the current color map size of the monitoring window. |
This method returns the number of video frames that were not captured during the current capture. The frame rate * capture time equals the missing frames + the captured frames.
| inout long frames | Returns the number of frames not output to the temporary file during the capture. |
| inout long captured_frames | Returns the number of frames captured. |
This method sets the sample rate on the audio device. Sample rates are set to the closest sample rate supported by the device. If the passed rate is supported, it returns Success. Otherwise, a ValueChange return code is returned, and actual setting is returned in parameter rate.
| inout long rate | Specifies the desired sample rate. Returns the actual setting if the return code is ValueChanged. |
This method returns the current sample rate on the audio device.
| inout long rate | Returns the current sample rate. |
This method sets the number of bits per sample on the audio device.
| in long bits | Specifies the value of bits per sample. |
The current setting of bits per sample is returned.
| inout long bits | Returns the current bits per sample setting. |
This method sets the audio format that is to be used for record. Formats supported are device specific. All devices are required to minimally support PCM, A_LAW, and MU_LAW.
| in string audio_format | Specifies the string of the desired audio format. |
This method returns the current format setting.
| out string audio_format | Returns the string of the current audio format. |
This method sets the number of audio channels for record.
| in long number | The number of channels for record. A value of 1 specifies mono and a value of 2 specifies stereo. |
The current setting of number_of_channels is returned.
| inout long number | The value of the current setting for the number of channels. |
This method sets the byte order for the data captured. Values of MSB and LSB are supported, meaning Big Endian and Little Endian, respectively. If the target file type is AVI the format must be LSB.
| in string byte_order | Values of MSB and LSB are supported. |
This method returns the byte order setting as a string value.
| out string byte_order | The byte order setting as a value of MSB or LSB. |
This method sets the number format for the audio data captured. Values of SIGNED, UNSIGNED, and TWOS_COMPLEMENT can be supported by the specific device.
| in string number_format | The desired number format as a string value. |
This method returns the number format setting as a string value.
| out string number_format | The number format setting as a string value of SIGNED, UNSIGNED, or TWOS_COMPLEMENT. |
This method enables audio input and output connectors. The specific audio device might have various input connector, for details, refer to the audio device manual. ACPA and 4231 support input connectors LINE_IN, HIGH_GAIN_MIC, and LOW_GAIN_MIC. Output connectors are LINE_OUT and HEADPHONE.
| in string audio_in | The string specifying the desired audio input. |
| in string audio_out | The string specifying the desired audio output. |
This method enables video input connector. Supported values are INPUT_COMPOSITE and INPUT_SVIDEO.
| in string video_in | The string specifying the desired video input. |
This method returns the current input and output connector of audio device.
| out string audio_in | The string value representing the current audio input setting. |
| out string audio_out | The string value representing the current audio output setting. |
This method returns the current input connector of video device.
| out string video_in | The string value representing the current video input setting. |
This method changes the audio volume of the monitor.
| in long volume | Specifies the desired volume of the monitor, valid range is 0 - 100. |
This method returns the current audio volume setting.
| inout long volume | Returns the current audio volume. |
This method sets the balance. Valid values are -100 to 100. -100 is full left and 100 is full right. 0 is balanced in the center.
| in long balance | The desired balance value. |
This method returns the current balance setting in the parameter balance.
| inout long balance | The current balance value. Possible value from -100 to 100, -100 is full left and 100 is full right. 0 is balanced in the center. |
This method returns the current state of the Capture object.
| inout StateType state | The state is a value from the enum StateType list, which can have values of NotReadyState, ReadyState, RecordState, PauseState, SaveState, or PendingState. |
This method returns the next event in the event queue. The event type is returned in the event_type parameter. The error_number parameter returns the error type if an error occurs, otherwise it returns 0.
For example, if event_type is RecordComplete and error_number is EFileIO, record stopped because of a file IO error. If event_type is SaveComplete and the error_number is 0, save completed successfully.
| inout EventType event | Returns the event type. The possible values are Error, RecordComplete, or SaveComplete. |
| inout long error_number | Returns the details of event. The possible values are 0, EAudioDevice, EVideoDevice, or EFileIO. |
This method returns a boolean into the pending parameter which states whether there is a pending event or not.
| inout boolean flag | Returns True if there is a pending event. |
This method returns an event handle. The application can use this handle as a file descriptor on which to select and thereby query events. If the file descriptor is readable, an event is queued.
| inout long handle | Returns event handle, a valid event handle should be a non-zero number. |
This method is used in the presentation of device specific capabilities that are shared for all invocations of the device. An example of this is the configuration of passing through CD-ROM audio data at the device level which is mixed at the device independent of other device usage. If you enable master setting mode, you share in this configuration of the device. If you choose not to participate in the master settings you must try to disable master_settings mode. Each device can enforce rules based on the current state and as to when the master_settings mode can be entered or exited. Some devices can not support master settings at all in which case a value of InvalidCommand is returned.
This method is used to disable the master setting mode on the audio device in use. If the method is not supported by the audio device in use a InvalidCommand value is returned. If the device can not be acquired with master setting disabled, a value of Failure is returned.
This UMSCapture object presents this method for the specific UMSAudioDevice object in use.
| inout boolean enabled | A boolean is returned indicating whether master settings are enabled or disabled for the audio device. |
This UMSCapture object presents this method for the specific UMSAudioDevice object in use.
| out string exec_pathname | The pathname of the requested executable is returned as a string. |
The audio device inputs alias and outputs alias are returned. These aliases are used in the configuration file to define the input and output connections on specific audio devices.
| out string inputs_alias | The audio device inputs alias is returned as a string. |
| out string outputs_alias | The audio device outputs alias is returned as a string. |
The specific audio device class is returned as a string.
| out string device_class | The specific audio device class in use is returned as a string. |
The specific audio device in use is returned as a string such as /dev/acpa0.
| out string device_pathname | The specific audio device in use is returned as a string. |
For introductory information, see Movie Capture and Playback Objects.