The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Video-CPL-0.10
River stage zero No dependents
++
/ Video::CPL

NAME

Video::CPL - Create and manipulate Coincident TV Programming Language (CPL) files.

VERSION

Version 0.10

SYNOPSIS

Video::CPL provides an object-oriented module for creating CPL files. CPL files control interactive video experiences.

A simple example might be displaying a video, e.g. from Youtube, in a player on a webpage.

A more complex example might include images, which the user clicks on to jump to other videos.

In conjunction with CGI.pm it is straightforward to create fully interactive web pages with dynamically created video experiences.

Video::CPL does not create the video file itself; it works with videos on services such as Youtube, or created with tools such as Video::FFmpeg.

A tutorial is available at http://metabase.coincident.tv/cpan.

Short code sample: create a file using CPL, and then embed a link to the file in your html as shown below.

    use CPL;
    my $ctv = new Video::CPL(videoSource=>"http://www.youtube.com/watch?v=0ZexPPDLXRA"
                             html=>$htmlfilelocation);
    $ctv->programEnd(30);   #end after 30 seconds
    print $ctv->print(); #prints out cpl file

    #and then, when writing html:
    print $ctv->embed();  #print out an HTML embed pointing to the temporary file

METHODS

new(videoSource=>$url,[backgroundHTML=>$url,frameHeight=>$k, frameWidth=>$k,loggingService=>$url,skinButtons=>$url, videoHeight=>$k,videoViewLayout=>$name,videoWidth=>$k, videoX=>$k,videoY=>$k,webViewLayout=>$name, xUniqueID=$string,xVersionCPL=>$string, xWebServiceLog=>$string],[html=>$loc,ref=>$url],[htmldir=>$dir,htmlurl=>$url) or new(initfromctv=$urlORxml);

    Create a new Video::CPL object. There is one videoSource per Video::CPL object.

    A videoSource such as videoSource=>"http://www.youtube.com/watch?v=0b75cl4-qRE", must be specified unless initializing from another Video::CPL file. All other parameters are optional; most of them are specified in the CPL language definition available from Coincident.tv. Additional file placement options are described below.

    initfromctv=>"foo.ctv" . Given a string which is either valid XML or a filename, use it to initialize the Video::CPL object.

    If the Video::CPL object will be output using the <b>xml()</b> method, there is no need to specify a location for it. It is convenient to specify a location where the Video::CPL XML can be accessed, if multiple Video::CPL objects interact, or if the <b>embed</b> or <b>print</b> methods will be used. 

    For automatic creation of a Video::CPL file, the location of a directory where the file can be created, along with the matching URL to reach that location, must be provided. An example would be <b>htmldir="/var/www/tmp"</b> and <b>htmlref=>"http://www.foo.com/tmp" </b>

asurl()

    Returns the URL which will recreate this URL. This will be a file or a reference to this script.

    Used when creating the media parameter for the CTV player, which requires a full URL.

asrel([$otherCPL])

    Returns the URL fragment (e.g. foo/goo.ctv) which will access this file from the current directory. If given
    a parameter of another Video::CPL object, will return a URL fragment which is valid in that objects context.

xVersionCPL([$string])

    Accessor routine to set or read xVersionCPL.

videoSource([$url])

    Accessor routine to set or read videoSource.

xWebServiceLoc([$url])

    Accessor routine to set or read xWebServiceLoc.

loggingService([$url])

    Accessor routine to set or read loggingService.

skinButtons([$url])

    Accessor routine to set or read skinButtons. These are optional, and used to form the control bar.

backgroundHTML([$url])

    Accessor routine to set or read backgroundHTML.

videoWidth([$string])

    Accessor routine to set or read videoWidth (the width of the video image within the overall CPL layout).

videoHeight([$string])

    Accessor routine to set or read videoHeight (the height of the video image).

frameWidth([$string])

    Accessor routine to set or read frameWidth (the width of the entire CPL frame).

frameHeight([$string])

    Accessor routine to set or read frameHeight (the height of the entire CPL frame).

videoX([$string])

    Accessor routine to set or read videoX.

videoY([$string])

    Accessor routine to set or read videoY.

videoViewLayout([$layoutname])

    Accessor routine to set or read videoViewLayout.

webViewLayout([$layoutname])

    Accessor routine to set or read webViewLayout.

youtubeID([$id])

    Accessor routine to set or read youtubeID.

xUniqueID([$id])

    Accessor routine to set or read xUniqueID.

xProgLevelDir([$id])

    Accessor routine to set or read xProgLevelDir.

video([$video1,$video2,$video3}])

    Accessor routine for the video field, which contains an array of three different video sources which can be used.
    Returns an array, or undef if it has not been set.
    Takes an array of 3 urls.
    There is no way to set an individual URL with this accessor; read and then write to set one.

v1($url)

    Accessor routine to get or set the first element of the video array.

v2($url)

    Accessor routine to get or set the second element of the video array.

v3($url)

    Accessor routine to get or set the third element of the video array.

tl($cuepointname)

    Create a targetList with one element.

parsectv()

newname("base")

    Returns a name of the form "basedddddddd" which is not used by any other cue point or annotation in this CPL object.

addcue($cue);

     Adds the created cue to the CPL object. This is not needed if reading the cue points from the video file itself, e.g. with a local .flv file.

newcue(%cueparms)

    Create a new Cue point with the given parameters, and set the parent to this CPL object.

story(text=>"some text",pic=>"foo.jpg")

     Shorthand to create a Video::CPL::Story object.

layout(%parms)

    Create a new layout and install it in this CPL. Pass the parameters on to Video::CPL::Layout::new.

layouts() return all layouts for the current Video::CPL as an array

layoutbyname($name)

    Return the layout with the given name.

allstories()

    Return an array with all of the Annotation based Story objects in this CPL.

numcue($k)

     Returns the k-th cuePoint Cue object. Note that a normally created CPL object will always create a cue point a the beginning, easily obtained with firstcue(), below.

cuePoints()

    Returns all Cue objects.

numwebcue(4)

     Returns the 4th webPoint object.

maxweb()

max()

firstcue()

     Returns the first cuePoint Cue object.

lastcue()

add() Adds a cue point to the end of the cue point list. The parent of the cue point should either not be set, or be correctly set. Cue points may only have one parent, and can therefore not be used in multiple CPL objects.

webPoints() return all webPoints for the current Video::CPL as an array

addwp()

addanno()

annotations()

webPoint(name=>"aname",interestURL=>"http://somewhere.com/foo.jpg",story=>{picLoc=>"foo.jpg"},tl=>[$target]});

    Create and add a new webPoint object.

    Target can be created with something like Video::CPL::Cue->new("Lost A");

    Story is currently just an anonymous hash. It may become an object in a future release.

goto(name=>"aname",tl=>[$target]});

    Create and add a new goto object.

    Target can be created with something like Video::CPL::Cue->new("Lost A");

regular(name=>"cuename",time=>1.0,interestURL=>"http://somewhere.com/foo.html");

    Create and add a new regular object.

insertPt(name=>"cuename",time=>1.0);

    Create and add a new regular object.

cuebyname($name)

    Return the first cue with the given name.

cuePointbyname($name)

    Return the first cuePoint with the given name.

webPointbyname($name)

    Return the first webPoint with the given name.

cuebytime($time)

    Return the cuePt with the given time, or undef.

annobyname("name")

    Return the first annotation with the given name.

programEnd()

returnEnd()

annotation()

    Create an annotation and add it to the object.

adecoration([annotation parameters])

agoto([annotation parameters])

    adecoration,agoto,ajavascript, and areturnend are shorthand notations to create an annotation and add it
    to the current Video::CPL object, setting the parent correctly. Generally they are recommended if the annotation
    will be used more than once.

    $anno = $cpl->agoto(balloonText=>"go somewhere",x=>10,y=>10,target=>$somecue);
    $cpl->numcue(1)->addanno($anno);

    For a single-use annotation, Annotation::goto may be more convenient.

    $cpl->regular(time=>10)->goto(balloontext=>"go somewhere",x=>10,y=>10);

    This would create a Cue and add an annotation in one statement.

    The annotation parameters are used with normal Annotation constructor; therefore Story parameters such as
    picLoc will cause a Story to be automatically generated.

ajavascript([annotation paramters])

areturnend()

     my $anno = $cpl->areturnend(balloonText=>"Return please",x=>10,y=>10);
     $cpl->numcue(0)->addanno($anno);

userChoice()

xmlo($xo)

    Add the XML to output this object to the existing XML::Writer object xo. Creation and printing is done outside this routine.

xml()

    Return the xml format of the current CPL object. This is normally called from print, but can
    be called directly.

print()

    Print out the current xml in the automatically created temporary file within the web-viewable file hiearchy. Use before calling embed.

embed([height=>yyy,width=>xxx])

    Return the html code used to embed a CPL screen within an html file. 

    The height and width parameters are optional, and may be specified as percent or pixels. If not specified, height will be set to 392 pixels and width to 680 pixels.

    CPL parameters that can be specified:
       height: Height in pixels or percent. Defaults to frameHeight else videoHeight else 680 pixels.
       width: Width in pixels or percent. Defaults to frameWidth else videoWidth else 415 pixels.
       player:  a URL that reaches the desired Flash player. If not specified, will default to a player
           at Coincident TV. This will not be able to access images etc. from a different server unless
           there is a file "crossdomain.xml" at the top level of that server. This file should look like

           <?xml version="1.0"?>
           <!DOCTYPE cross-domain-policy SYSTEM "http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
           <cross-domain-policy>
           <allow-access-from domain="*" />
           <site-control permitted-cross-domain-policies="all"/>
           </cross-domain-policy>

       media: the URL of the media CTV. If a partial URL, it will be relative to the player.
       mergedstyle: if true, include the media as a CGI parameter to the player. This is the norm when using the full CPL experience.

    Additional Adobe parameters:
        align:  defaults to "middle".
        play:   defaults to "true".
        quality: defaults to "autohigh".
        allowfullscreen: defaults to "true".
        allowScriptAccess: defaults to "always". In this mode, a webPoint reached from "embed"-ed player
            will overwrite the window.
        type:   defaults to "application/x-shockwave-flash".
        pluginspage: defaults to "http://www.adobecom/go/getflashplayer".
        bgcolor: Hex value,defaults to "#869ca7".

Video::CPL::checkready(local=>$file)

     This is a function, and not a method. Typically it is called before creating a CPL object

isyoutube($url)

    Return true if this URL appears to be a Youtube video.

AUTHOR

Carl Rosenberg, <perl at coincident.tv>

BUGS

Please report any bugs to Coincident TV.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc CPL

ACKNOWLEDGEMENTS

This is actually just a straightforward interface to the work done by the rest of the Coincident team.

LICENSE AND COPYRIGHT

Copyright 2010 Coincident TV

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.