Kamaelia docs : Kamaelia.Codec.YUV4MPEG

Kamaelia.Codec.YUV4MPEG

component FrameToYUV4MPEG
component YUV4MPEGToFrame

Parsing and Creation of YUV4MPEG format files
UNCOMPRESSED FRAME FORMAT

Parsing and Creation of YUV4MPEG format files

YUV4MPEGToFrame parses YUV4MPEG format data sent to its "inbox" inbox and sends video fram data structures to its "outbox" outbox.

FrameToYUV4MPEG does the reverse - taking frame data structures sent to its "inbox" inbox and outputting YUV4MPEG format data to its "outbox" outbox."

The YUV4MPEG file format is supported by many tools, such as mjpegtools, mplayer/mencoder, and ffmpeg.

Example Usage

Playback a YUV4MPEG format file:

Pipeline( RateControlledFileReader("video.yuv4mpeg",readmode="bytes", ...),
          YUV4MPEGToFrame(),
          VideoOverlay()
        ).run()

Decode a dirac encoded video file to a YUV4MPEG format file:

Pipeline( RateControlledFileReader("video.dirac",readmode="bytes", ...),
          DiracDecoder(),
          FrameToYUV4MPEG(),
          SimpleFileWriter("output.yuv4mpeg")
        ).run()

YUV4MPEGToFrame Behaviour

Send binary data as strings containing YUV4MPEG format data to the "inbox" inbox and frame data structures will be sent out of the "outbox" outbox as soon as they are parsed.

See below for a description of the uncompressed frame data structure format.

This component supports sending data out of its outbox to a size limited inbox. If the size limited inbox is full, this component will pause until it is able to send out the data. Data will not be consumed from the inbox if this component is waiting to send to the outbox.

If a producerFinished message is received on the "control" inbox, this component will complete parsing any data pending in its inbox, and finish sending any resulting data to its outbox. It will then send the producerFinished message on out of its "signal" outbox and terminate.

If a shutdownMicroprocess message is received on the "control" inbox, this component will immediately send it on out of its "signal" outbox and immediately terminate. It will not complete processing, or sending on any pending data.

FrameToYUV4MPEG Behaviour

Send frame data structures to the "inbox" inbox of this component. YUV4MPEG format binary string data will be sent out of the "outbox" outbox.

See below for a description of the uncompressed frame data structure format.

The header data for the YUV4MPEG file is determined from the first frame.

All frames sent to this component must therefore be in the same pixel format and size, otherwise the output data will not be valid YUV4MPEG.

UNCOMPRESSED FRAME FORMAT

A frame is a dictionary data structure. It must, at minimum contain the first 3 ("yuv", "size" and "pixformat"):

{
  "yuv" : (y_data, u_data, v_data)  # a tuple of strings
  "size" : (width, height)          # in pixels
  "pixformat" :  pixelformat        # format of raw video data
  "frame_rate" : fps                # frames per second
  "interlaced" : 0 or not 0         # non-zero if the frame is two interlaced fields
  "topfieldfirst" : 0 or not 0      # non-zero the first field comes first in the data
  "pixel_aspect" : fraction         # aspect ratio of pixels
  "sequence_meta" : metadata        # string containing extended metadata
                                    # (no whitespace or control characters)
}

All other fields are optional when providing frames to FrameToYUV4MPEG.

YUV4MPEGToFrame only guarantees to fill inthe YUV data itself. All other fields will be filled in if the relevant header data is detected in the file.

The pixel formats recognised (and therefore supported) are:

"YUV420_planar"
"YUV411_planar"
"YUV422_planar"
"YUV444_planar"
"YUV4444_planar"
"Y_planar"

Kamaelia.Codec.YUV4MPEG.FrameToYUV4MPEG

class FrameToYUV4MPEG(Axon.Component.component)

FrameToYUV4MPEG() -> new FrameToYUV4MPEG component.

Parses uncompressed video frame data structures sent to its "inbox" inbox and writes YUV4MPEG format binary data as strings to its "outbox" outbox.

Inboxes

Outboxes

Methods defined here

Warning!

You should be using the inbox/outbox interface, not these methods (except construction). This documentation is designed as a roadmap as to their functionalilty for maintainers and new component developers.

canShutdown(self)

Returns true if the component should terminate when it has finished processing any pending data.

checkShutdown(self)

Collects any new shutdown messages arriving at the "control" inbox, and ensures self.shutdownMsg contains the highest priority one encountered so far.

main(self)

Main loop

mustShutdown(self)

Returns true if the component should terminate immediately.

sendoutbox(self, data)

Generator.

Sends data out of the "outbox" outbox. If the destination is full (noSpaceInBox exception) then it waits until there is space. It keeps retrying until it succeeds.

If the component is ordered to immediately terminate then "STOP" is raised as an exception.

write_frame(self, frame)

Generator.

Writes out YUV4MPEG format frame marker and data.

write_header(self, frame)

Generator.

Sends the YUV4MPEG format header to the "outbox" outbox, based on attributes of the supplied frame data structure.

Kamaelia.Codec.YUV4MPEG.YUV4MPEGToFrame

class YUV4MPEGToFrame(Axon.Component.component)

YUV4MPEGToFrame() -> new YUV4MPEGToFrame component.

Parses YUV4MPEG format binarydata, sent as strings to its "inbox" inbox and outputs uncompressed video frame data structures to its "outbox" outbox.

Inboxes

Outboxes

Methods defined here

Warning!

init(self)

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

checkShutdown(self)

Collects any new shutdown messages arriving at the "control" inbox, and returns "NOW" if immediate shutdown is required, or "WHENEVER" if the component can shutdown when it has finished processing pending data.

main(self)

Main loop

readbytes(self, size)

Generator.

Read the specified number of bytes from the stream of chunks of binary string data arriving at the "inbox" inbox.

Any excess data is placed into self.remainder ready for the next call to self.readline or self.readbytes.

Data is only read from the inbox when required. It is not preemptively fetched.

The read data is placed into self.bytesread

If a shutdown is detected, self.bytesread is set to "" and this generator immediately returns.

readline(self)

Generator.

Read up to the next newline char from the stream of chunks of binary string data arriving at the "inbox" inbox.

Any excess data is placed into self.remainder ready for the next call to self.readline or self.readbytes.

Data is only read from the inbox when required. It is not preemptively fetched.

The read data is placed into self.bytesread

If a shutdown is detected, self.bytesread is set to "" and this generator immediately returns.

safesend(self, data, boxname)

Generator.

Sends data out of the named outbox. If the destination is full (noSpaceInBox exception) then it waits until there is space and retries until it succeeds.

If a shutdownMicroprocess message is received, returns early.

Feedback

Got a problem with the documentation? Something unclear that could be clearer? Want to help improve it? Constructive criticism is very welcome - especially if you can suggest a better rewording!

Please leave you feedback here in reply to the documentation thread in the Kamaelia blog.

-- Automatic documentation generator, 05 Jun 2009 at 03:01:38 UTC/GMT

Kamaelia is an open source project originated from and guided by BBC Research. For more information browse the site or get in contact.

This is an ongoing community based development site. As a result the contents of this page is the opinions of the contributors of the pages involved not the organisations involved. Specificially, this page may contain personal views which are not the views of the BBC. (the site is powered by a wiki engine)