The BeEmbedMedia helper is used to create and display every type of multimedia object as Video, Audio, Image, Application (like Flash object) or generic multimedia file (BEFile). This helper is always included in backend AppController, as well as in every frontend application by inheritance, so inserting a video, a Flash swf file or an image is as easy as using a CakePHP helper. The helper uses Flowplayer as internal flash player for native visualization of video and audio objects but also allow the embedding of provider players when there's no direct link to flv file (i.e youtube see figure 1, 2).
Let's see how:

Essentially this helper provides a function called "object" that works generically for any Bedita object:

public function object ( $obj, $params = null, $htmlAttributes=array() )

The $obj parameter represent the BEdita object that has to be displayed in the frontend. Generically in your view code, you'll have a multidimensional array:

$section["currentContent"]["relations"]["attach"]

which contains a list of all related media objects, i.e. all the media objects which share a "relation" of type "attach" with "currentContent" inside the "section".

$params

$params represent an array of specific parameters related to the type of object to display. There's few parameters handled internally by BEdita. The main of those is "presentation" params which define how the multimedia objects have to be shown. This parameter has a default value for any multimedia object so while for an image object will be create a thumbnail, for video object will be loaded the flash player.

You can force presentation type passing the value in $params associative array. It can be "thumb" , "full" or "link".
For example, the code:

{assign_associative var="params" presentation="thumb" width=200 mode="crop"}
{foreach from=$section.currentContent.relations.attach item="media"}
   {$beEmbedMedia->object($media,$params)}
{/foreach}

Will try to show the contents of array "attach" with thumbnails, regardless of the specific object. For example in case of a video object, will display the associated thumbnail if present, while in case of an image stored on BEdita, will try to generate thumbnail runtime or reusing a thumbnail previously created.

The "presentation=full" type will display the full visualization of the object embedding directly the video or the audio or the images object.
The code:

{assign_associative var="params" presentation="full"}
{foreach from=$section.currentContent.relations.attach item="media"}
   {$beEmbedMedia->object($media,$params)}
{/foreach}

Will try to display the video and audio object type with the internal default player, if "useProviderPlayer" variable is present in $params the function will try to embed the object using directly the related provider player. The image object type will be shown in their real dimension using the original file uploaded.

Moreover, $params can contain object-specific parameters such as flashvar variables for customize Flowplayer or, more generically, any type of variable that is required to displaying multimedia objects.
For examples:

{assign_associative var="clips" autoPlay=true}
{assign_associative var="flashVars" clip=$clips}
{assign_associative var="params" flashvars=$flashVars}
{foreach from=$section.currentContent.relations.attach item="media"}
    {$beEmbedMedia->object($media,$params)}
{/foreach}

Enable the autoplay function, when display a video with flowplayer.

The "presentation=link" parameter will produce a well formatted anchor pointing to the resource itself, with the title of the object inserted inside anchor tag.
Finally the URLonly parameter will force the helper to return only the URL, that can be useful when you want use manually the "img" tag.

{assign_associative var="params" presentation=link URLonly=true}
{foreach from=$section.currentContent.relations.attach item="media"}
   < img src="{$beEmbedMedia->object($media,$params)}" alt="" />
{/foreach}

$htmlAttributes

The $htmlAttributes represents the html parameters of the embedding object. Here you can specify all the html attributes like rel, width, height, id, etc...

These was just an overview of the main features of the BeEmbedMedia helper, you can try by yourself all options and eventually ask help on the official forum. Some useful links are reported in the right column.