The UMSMPEG1VideoEncoder object allows the user to compress video image frames into an MPEG-1 data format using a selectable ratio of I, P and B frames (intra-frames, predicted-frames, and bi-directional frames). MPEG-1 is an international standard (ISO document number 11172-2), with video quality equal to Motion-JPEG for file sizes that are 2-4 times smaller than Motion-JPEG files.
The UMSMPEG1VideoEncoder object is used to convert video image data into an MPEG-1 video sequence. This object can accept input image data that is either YUV (subsampled U and V) or PadRGB24. The compressed bit rate is also user selectable, with a typical rate of 1.2 megabits per second for either 24 or 30 frame-per-second sequences, using frame dimensions of 352 by 240 pixels.
To learn more about the UMSMPEG1VideoEncoder object, see:
For introductory information, see Video Codec Objects.
enum ReturnCode {
Success, //Command completed successfully
Failure, //Bad parameter or execution failure
UnsupportedFormat, //Input image format is not supported
OutOfRange, //Bad input parameter value
OutOfMemory, //Failure trying to allocate internal memory
UnsupportedValue, //The parameter value requested is not supported
ChangedFrameType, //Requested frame type was changed by encoder object
FramesRemaining //A FirstFrame was received with frames remaining
};
enum ImageFormatIn {
YUVPlanar, //Input image format is Y, U, V (separate planes)
RGB24 //Input image format is 0,R,G,B (32-bits per pixel)
};
enum FrameType {
FirstFrame, //First frame of the sequence
IFrame, //Intra-frame
PFrame, //Predicted frame (set by the Encoder Object)
BFrame, //Bi-directional frame (set by the Encoder Object)
LastFrame, //Last frame of the sequence
Unspecified //Frame type to be determined by the Encoder Object
};
enum FrameRate {
R_23Point9, //23.976 fps
R_24, //24 fps
R_25, //25 fps
R_29Point9, //29.970 fps
R_30, //30 fps
R_50, //50 fps
R_59Point9, //59.94 fps
R_60 //60 fps
};
The MPEG-1 video encoder has several user selectable parameters that influence image quality and file size. The bit rate determines the number of bits allocated, on average, to one second of compressed data. In addition, the ratio of intra-frames (I-frames), difference frames (P-frames) and bi-directional difference frames (B-frames) may be controlled over a limited range. The image quality, which is directly related to the bits per frame, and file size, are a function of frame rate, frame size, video content, types of video frames used for encoding, and the average bit rate.
The bit rate for the video stream is controllable over a range of roughly 1.0 to 3.0 megabits per second. A video bit rate of approximately 1.2 megabits per second should result in an overall MPEG-1 data rate of 1.5 megabits per second after audio data and headers are added. This data rate should result in good image quality for most video sequences. It is important to note that visual quality will vary with video content. Images with a lot of detail and/or fast motion require a relatively higher data rate for accurate encoding.
There are three different types of frames that can be encoded in MPEG-1: I-frame (largest size), P-frame, and B-frame (smallest), where size refers to the total number of bits in the compressed frame. The relative frame sizes are approximately as follows: I:P 3:1, I:B 10:1. A smaller file will result as more B-frames are used, with only a minimal quality degradation. In general, an I-frame interval of between 10 and 30 frames should be used. Setting the P-frame interval to zero results in an all I-frame sequence. Setting the P-frame interval to 1 results in a sequence with only I and P frames. A P-frame interval of 3 results in the typical 'PBBP' frame sequence that contains approximately 50% B-frames. Once the relative frequency for each of the frame types is selected, this frame pattern is applied to the entire file.
This method converts an input image frame to a compressed frame, storing the result in the user supplied buffer. In addition, the user may specify the frame type to be compressed. The first and last frames must be identified and, if the remaining frames are labeled 'Unspecified', then the encoder uses the I and P frame intervals to determine the frame type and return the frame type to the user.
If the P frame interval is three, then the encoder will be creating pairs of B frames. In this case, due to the MPEG-1 algorithm, the encoding order is not the temporal order and the first two temporal frames to be converted into B frames must be buffered and compressed after the 4th temporal frame. This out-of-order encoding also means that the encoder returns compressed frames after the last temporal frame is supplied. Thus, any time that B-frames are being used for a compressed video sequence, the client should continue calling the compress_frame method, even after the last temporal frame, until the return length of the compressed frame equals zero. Also, because the first two B-frames are buffered by the encoder, a frame length of zero is returned for these frames.
This method allows the client to query the bit rate setting.
| inout long bits_per_second | This argument reads the bits per second setting. |
This method allows the client to query the frame rate setting.
| inout FrameRate frame_rate | This argument holds the return enum value for the frame rate. |
This method allows the client to query the I-frame interval setting.
| inout long iframe_interval | This argument allows the user to query the I-frame interval. |
This method allows the client to query the image format setting.
| inout ImageFormatIn image_format | This argument gets the input image format. |
This method allows the client to query the input image dimension setting.
| inout long width | The returned width setting. |
| inout long height | The returned height setting. |
This method allows the client to determine the maximum compressed frame to be returned by the encoder.
| inout long buffer_size | This argument holds the maximum compressed frame buffer size value. |
This method allows the client to query the P-frame interval setting.
| inout long iframe_interval | This argument holds the return value for the P-frame interval. |
This methods sets the average bits allocated for one second of video data. By adjusting the quality level for each frame, the encoder attempts to maintain a fairly constant data rate. Note that it may be impossible for the encoder to meet the desired data rate.
| in long bits_per_second | This argument determines the bits allocated to one second of compressed video data. |
This method allows the client to select the frame rate from a range of permissible values.
| in FrameRate frame_rate | This argument holds the enum values for setting the frame rate. |
This method sets the frequency for I-frames within the video sequence.
| in long iframe_interval | This argument allows the user to set the I-frame interval. |
This method selects the input image format. If the input image format is selected as YUVPlanar, the data is formatted as a full-size Y plane, followed by a 1/4 size U plane, followed by a 1/4 size V plane. Each value is 8 bits. If the input data is formatted as RGB24, then each pixel is formatted as zero, red value, green value, blue value (32-bits per spatial pixel), with each color component an 8-bit value.
| in ImageFormatIn image_format | This argument specifies the input image format. |
This method allows the client to set the width and height dimensions for the input image frames. Note that the width is limited to a maximum of 352 and the height to a maximum of 288.
| in long width | This argument allows the client to specify image width. |
| in long height | This argument allows the client to specify image height. |
This method sets the frequency for P-frames and B-frames within the video sequence. Pairs of B-frames are created if the P-frame interval is set to three.
| in long pframe_interval | This argument allows the user to set the P-frame interval. |
For introductory information, see Video Codec Objects.