MediaPlugin < System

You are here: Foswiki>System Web>MediaPluginEditAttach
---+!! Media Plugin

%SHORTDESCRIPTION%.

Uses the =OBJECT= html tag to embed arbitrary content into a page, with a particular bent towards media: common media formats are detected and some "agnostic best-guess" html is used (derived from that recommended by
the plugin providers).
However, any content can be embedded using the object tag: java, pdf, other html, svg, even images (although for the latter is of course no real reason to do so this way).
The plugin uses generic syntax when it cannot detect the type of file being embedded.

The plugin stores a range of default values (defined here on this page)
which allow you to specify a bare minimum of info in your markup and still
get acceptable results (see [[#Basic_Usage][Basic Usage]] below).
These defaults can of course be overridden on a use-by-use basis.

%TOC%

---++ Basic Usage

You *could* call the plugin as simply as:

<verbatim>
%MEDIA{"SomeMovie.mov"}%
</verbatim>

This will detect that the embedded file is a !QuickTime and use "media-like" syntax (and pass the correct =classid= to IE - why it can't work out which plugin to use is a little beyond me). However, unlike an =IMG= tag, plugins do not autosize to their content, and the movie would display at the default size. You could use media of only one size site-wide and specify the dimensions as defaults, but realistically the minimum markup you need to embed things into your wiki pages is:

=%<nop>MEDIA{"SomeMovie.swf" width="320" height="180"}%=

---++ Advanced Usage

A call to the !MediaPlugin could get as complicated as:

<verbatim>
%MEDIA{
src="SomeMovie.wmv"
width="320"
height="180"
controller="FALSE"
play="TRUE"
myparam1="3.1419"
myparam2="edinburgh"
}%
</verbatim>

See for possible attributes below.

Note that !MediaPlugin figures out the correct mime type parameter so that the correct plugin will be called to deal with that content.

---++ Syntax

!MediaPlugin supports arbitrary parameters. If you pass it =cowtype="Jersey"=, it will passed on to the browser.

A few parameters are defined and get handled a little differently (they may be "translated" to a particular browser plugins syntax).

| *Parameter*  | *Value* | *Description* | *Notes* |
| =""=, =src=, =data=        | URI or file name | The content to embed. Relative URIs are interpreted with respect to the =codebase= attribute if it is given. | |
| =width=      | Standard web measure (px, %, em) | Width of box holding content | |
| =height=     | Standard web measure (px, %, em) | Height of box holding content| |
| =controller= | text boolean ("TRUE" or "FALSE")| Whether to display controls|automatically added |
| =play=       | text boolean | whether to auto-play the content| Automatically added for !QuickTime and Flash |

---+++ Syntax for !QuickTime mov

See [[http://www.apple.com/quicktime/tutorials/embed2.html][Overview of Embed Tag Attributes]] for !QuickTime.

---+++ Syntax for Flash swf

Pass Flash movie attributes within the =%<nop>MEDIA{...}%= accolades (all values within quotes). When a particular parameter is not specified, the default value will be used (see table below).

%TWISTY{
remember="on"
prefix="<h4>"
mode="div"
showlink="&#9658; Attributes for Flash"
hidelink="&#9660; Attributes for Flash"
suffix="</h4>"
}%
%TABLE{sort="off" headeralign="left" databg="#ffffff"}%
| *Parameter*   | *Description*   | *Example*   |
| <strong>Required attributes</strong>  ||||
| =src=     | Filepath of the movie; should have suffix =.swf= ("src=" can be omitted) | =mypath/flashmovie.swf= |
| <strong>General attributes</strong>  |||
| =width=  | Width of Flash movie in pixels, or a percentage. 100% means one hundred percent of the available width on the page. | ="50%"= or ="500px"= |
| =height=  | Height of Flash movie in pixels, or a percentage. 100% means one hundred percent of the available height on the page. | ="50%"= or ="500px"= |
| =bgcolor= | Background color of Flash movie in hex string. When omitted, no background color will be specified and the background color of the Flash movie will be used. | ="#cccccc"= |
| <strong>Advanced attributes</strong>  |||
| =align= | Default centers the movie in the browser window and crops edges if the browser window is smaller than the movie. =l= (left), =r= (right), =t= (top), and =b= (bottom) align the movie along the corresponding edge of the browser window and crop the remaining three sides as needed. | ="l"=, ="r"=, ="t"=, ="b"= |
| =salign= | =l=, =r=, =t=, and =b= align the movie along the left, right, top or bottom edge, respectively, of the browser window and crop the remaining three sides as needed. %BR% \
=tl= and =tr= align the movie to the top left and top right corner, respectively, of the browser window and crop the bottom and remaining right or left side as needed. %BR% \
=bl= and =br= align the movie to the bottom left and bottom right corner, respectively, of the browser window and crop the top and remaining right or left side as needed. | ="l"=, ="t"=, ="r"=, ="b"=, ="tl"=, ="tr"=, ="bl"=, ="br"= |
| =scale= | Scaling of Flash movie. | ="noborder"=, ="exactfit"=, ="noscale"=, ="showall"= |
| =quality= | Playback quality. | ="best"=, ="high"=, ="medium"=, ="low"=, ="autohigh"=, ="autolow"= |
| =menu= | Should right-click on Flash movie show a (default) menu? Note that with the Flash 7 player the menu cannot be removed. | ="true"= or ="false"= |
| =id=     | ID of Flash movie; should be the same value as =name= (specify both) | ="movie2"= |
| =wmode= | Sets the Window Mode property of the Flash movie for transparency, layering, and positioning in the browser. %BR% \
=window= - movie plays in its own rectangular window on a web page. %BR% \
=opaque= - the movie hides everything on the page behind it. %BR% \
=transparent= - the background of the HTML page shows through all transparent portions of the movie, this may slow animation performance. | ="window"=, ="opaque"= or ="transparent"= |
| =play= | Specifies whether the movie begins playing immediately on loading in the browser. | ="true"= or ="false"= | 
| =loop= | Specifies whether the movie repeats indefinitely or stops when it reaches the last frame. | ="true"= or ="false"= |
| =allowscriptaccess= | Controls the ability to perform outbound scripting from within a Flash SWF. %BR% \
When allowScriptAccess is =never=, outbound scripting always fails. %BR% \
When allowScriptAccess is =always=, outbound scripting always succeeds. %BR% \
If allowScriptAccess is =sameDomain= (it is supported in SWFs from Flash Player 8), outbound scripting is allowed only if the SWF file resides in the same domain as the hosting web page. | ="sameDomain"=, ="always"= or ="never"= |
| =fullscreen= | Enabled scriptable fullscreen mode. An overlay dialog box will appear when the movie enters full-screen mode, instructing the user how to exit and return to normal mode. The dialog box appears for a few seconds and then fades out. | ="true"= or ="false"= |
| =base= | Specifies the base directory or URL used to resolve all relative path statements in the Flash Player movie. This attribute is helpful when your Flash Player movies are kept in a different directory from your other files. | any directory URL, or empty string =""= |
| =swliveconnect= | Specifies whether the browser should start Java when loading the Flash Player for the first time. | ="true"= or ="false"= |
| =flashvars= | Variables to be passed to the Flash movie. Multiple variables are separated by =&amp;=. | =flashvars="x=50&y=100&url=%<nop>ATTACHURL%/picture.jpg"= |
%ENDTWISTY%

More information on  [[http://kb.adobe.com/selfservice/viewContent.do?externalId=tn_12701&sliceId=1][Flash OBJECT and EMBED tag attributes]] (Adobe !TechNote).

---++ Syntax for generic objects
The attributes described at Syntax above is mostly all you need. For advanced usage see the table below.

%TWISTY{
remember="on"
prefix="<h4>"
mode="div"
showlink="&#9658; Attributes for generic objects"
hidelink="&#9660; Attributes for generic objects"
suffix="</h4>"
}%
%TABLE{sort="off" headeralign="left" databg="#ffffff"}%
| *Parameter*   | *Value* | *Description*   |
| =align= | left, right, top, bottom | Defines the text alignment around the object |
| =archive= | URL | A space separated list of URL's to archives. The archives contains resources relevant to the object |
| =border= | pixels | Defines a border around the object |
| =classid= | class ID | Defines a class ID value as set in the Windows Registry or a URL |
| =codebase= | URL | Defines where to find the code for the object |
| =codetype= | MIME type | The internet media type of the code referred to by the classid attribute |
| =data= | URL | Defines a URL that refers to the object's data |
| =declare= | declare | Defines that the object should only be declared, not created or instantiated until needed |
| =height= | pixels | Defines the height of the object |
| =hspace= | pixels | Defines the horizontal spacing around the object |
| =name= | unique_name | Defines a unique name for the object (to use in scripts) |
| =standby= | text | Defines a text to display while the object is loading |
| =type= | MIME_type | Defines the MIME type of data specified in the data attribute. See [[http://www.iana.org/assignments/media-types/][MIME Media Types]]. |
| =usemap= | URL | Specifies a URL of a client-side image map to be used with the object |
| =vspace= | pixels | Defines the vertical spacing around the object |
| =width= | pixels | Defines the width of the object |
%ENDTWISTY%

---++ Syntax for wmv
Sorry - I could not find any page for this.

---++ Examples

---+++ wmv
<verbatim>
%MEDIA{
"http://support.microsoft.com/support/mediaplayer/wmptest/samples/new/mediaexample.wmv"
height="240"
width="320"
}%
</verbatim>
generates:

%MEDIA{
"http://support.microsoft.com/support/mediaplayer/wmptest/samples/new/mediaexample.wmv"
height="240"
width="320"
}%

---+++ mov
<verbatim>
%MEDIA{
"%ATTACHURL%/sample.mov"
height="180"
width="320"
}%
</verbatim>
generates:

%MEDIA{
"%ATTACHURL%/sample.mov"
height="180"
width="320"
}%

By default the controller is shown (unless attribute =controller="false"=), and the controller height (16px) is automatically added to the movie height.

---+++ swf
<verbatim>
%MEDIA{
"%ATTACHURL%/sample.swf"
height="180"
width="320"
}%
</verbatim>
generates:

%MEDIA{
"%ATTACHURL%/sample.swf"
height="180"
width="320"
}%

---+++ swf with params
These are just a number of example parameters; not all are effective in this movie.
<verbatim>
%MEDIA{
src="%ATTACHURL%/swf/ThumbController.swf"
width="430"
height="370"
bgcolor="#ffffff"
menu="false"
base="%ATTACHURL%/swf/"
}%
</verbatim>
generates:

%MEDIA{
src="%ATTACHURL%/swf/ThumbController.swf"
width="430"
height="370"
bgcolor="#ffffff"
menu="false"
base="%ATTACHURL%/swf/"
}%

---+++ Flash from other sites

---++++ Yahoo Maps in Flash
<verbatim>
%MEDIA{
"http://developer.yahoo.com/maps/flash/V3.5/asGS.01.swf" 
base="http://developer.yahoo.com/maps/flash/V3.5/"
width="600px"
height="400px"
}%
</verbatim>

%MEDIA{
"http://developer.yahoo.com/maps/flash/V3.5/asGS.01.swf" 
base="http://developer.yahoo.com/maps/flash/V3.5/"
width="600px"
height="400px"
}%


---+++ pdf
<verbatim>
%MEDIA{
"http://www.pdf-tools.com/public/downloads/whitepapers/whitepaper-pdfprimer.pdf"
width="100%"
height="100%"
}%
</verbatim>
generates:

%MEDIA{
"http://www.pdf-tools.com/public/downloads/whitepapers/whitepaper-pdfprimer.pdf"
width="100%"
height="100%"
}%

---+++ mp3
<verbatim>
%MEDIA{
"%ATTACHURL%/test.mp3"
play="false"
autoplay="false"
height="20"
}%
</verbatim>
generates:

%MEDIA{
"%ATTACHURL%/test.mp3"
play="false"
autoplay="false"
height="20"
}%

---+++ wav
<verbatim>
%MEDIA{
"%ATTACHURL%/test.wav"
play="false"
autoplay="false"
height="20"
}%
</verbatim>
generates:

%MEDIA{
"%ATTACHURL%/test.wav"
play="false"
autoplay="false"
height="20"
}%


---+++ midi
<verbatim>
%MEDIA{
"%ATTACHURL%/test.mid"
play="false"
autoplay="false"
height="20"
}%
</verbatim>
generates:

%MEDIA{
"%ATTACHURL%/test.mid"
play="false"
autoplay="false"
height="20"
}%

---++ Notes for developers
---+++ Detection of media type / recommended plugin syntax

The plugin detects most media types and uses a hybrid of the html markup
recommended by the browser plugin makers - in the hope of providing maximum compatibility.
This is done simply by checking the extension of the filename. Or, if the filename contains =youtube.com= it will automatically use Flash.

Originally, the plugin used (almost) the exact recommended HTML on a type-by-type basis, but I've abandoned this in favor of "one markup fits all" because you don't know which plugin will be handling what - the various ISO formats (MPEG1,2,4, MP3) will be taken by whatever plugin was installed last, and !QuickTime now handles Windows Media on Macintosh systems (at Microsoft's recommendation!).

While most of the HTML is as generic as possible, the =classid= value and some
other mime-type information is unique to a particular file-type, and for Flash,
!QuickTime and Windows Media the Microsoft-sanctioned values are sent.
I understand MSIE has to have this info or it totally burns ...

I haven't bothered with Real. If there's huge demand, it wouldn't be hard to add - but it may also be handled quite well by the generic media syntax already.


---+++ Defining additional file formats
The output of this plugin is partially governed by Foswiki templates. The =mov= file output is defined in =templates/objectplugin_mov.tmpl=:
<verbatim>
%TMPL:DEF{"object"}%<object{MP_OBJECT_ATTRIBUTES}>{MP_OBJECT_PARAMS}<embed{MP_EMBED_ATTRIBUTES}/></object>%TMPL:END%
</verbatim>
Placeholders ={MP_...}= are replaced by =%<nop>MEDIA{...}%= parameters. 

To add other types add your own template using the same naming scheme (=objectplugin_ext.tmpl=).


---++ Plugin Settings
Change default settings in [[%SCRIPTURL{"configure"}%/#MediaPlugin$Extensions][configure]].

<!--
   * Set SHORTDESCRIPTION = Embed multimedia objects such as Flash or <nop>QuickTime in topics
-->
%TABLE{databg="#ffffff"}%
| *Configure setting* | *Meaning* | *Default* |
| ={Width}= | Default width of player  | =320= |
| ={Height}= | Default height of player  | =180= |
| ={<nop>ShowController}= | Switch that defines if the controller is shown  | =1= |
| ={<nop>AutoPlay}= | Switch that defines if the media is played automatically  | =1= |
| ={Debug}=  | If set to =1=, writes debugging info to =data/debug.txt= | =0= |

   
---++ Installation Instructions
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in =configure=, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.



---++ Plugin Info

|  Plugin Authors: | TWiki:Main.PiersGoodhew, Foswiki:Main.SvenDowideit, Foswiki:Main.ArthurClemens |
|  Copyright: | &copy; 2006 TWiki:Main.PiersGoodhew, 2008-2009 Foswiki:Main.SvenDowideit, Foswiki:Main.ArthurClemens |
|  License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
|  Version: | 12678 (2011-10-01) |
|  Release: | 1.3.4 |
|  Change History: | <!-- specify latest version first -->&nbsp; |
|  01 Oct 2011 | 1.3.4 Arthur Clemens: Fixed an issue where the filetype was not read if it was appended with a query string. Fixes a bug where default attributes read from the =tmpl= could not be overridden. Added audio examples. |
|  13 Sep 2009 | 1.3.3 Arthur Clemens: small refactoring; moved default settings to Configure. |
|  22 Jun 2009 | 1.3.2 Arthur Clemens: Fixed call to unreleased internal function =openAttachment=. |
|  20 Jun 2009 | 1.3.1: Arthur Clemens: Fixes media type lookup. For performance, plugin settings must now be done in %MAINWEB%.SitePreferences. |
|  08 Mar 2009 | 1.3: Mime types are now automatically added, so it is easier to get the browser call the right browser plugin. |
|  08 Mar 2009 | 1.2: Integrated !EmbedFlashPlugin; major code refactoring. |
|  03 Mar 2009 | !ObjectPlugin renamed to !MediaPlugin |
|  20 Feb 2009 | Ported to Foswiki |
|  20 Oct 2008 | Modernise with Foswiki:Extensions.BuildContrib, add EMBED Tag, remove !WikiWord issues, templatise html output, add !YouTube supprt - Foswiki:Main.SvenDowideit |
|  16 Oct 2006 | Initial version |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  Dependencies: | None |
|  Plugin Home: | http://foswiki.org/Extensions/MediaPlugin |
|  Support: | http://foswiki.org/Support/MediaPlugin |

<!-- Do _not_ attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the feedback topic on foswiki.org instead. -->
Topic attachments
I	Attachment	Action	Size	Date	Who
fla	sample.fla	manage	42.5 K	19 Nov 2008 - 17:24	UnknownUser
html	sample.html	manage	0.1 K	01 Nov 2008 - 18:22	UnknownUser
mov	sample.mov	manage	21.2 K	01 Nov 2008 - 18:22	UnknownUser
swf	sample.swf	manage	1.9 K	19 Nov 2008 - 17:24	UnknownUser
Topic revision: r1 - 08 Mar 2009, ProjectContributor
System
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback