\" these two registers are probably groff-only
.nr PORPHANS 3
.nr HORPHANS 3
.TL
SWFPut \(em Flash and HTML5 Video Plugin for WordPress
.AU
Ed Hynan <edhynan@gmail.com>
.AB no
This `README' serves as the main documentation
for the \fBSWFPut\fP \fIWordPress\fP plugin, and
as the conventional `README' as well.
.AE
<<CMAC>>
.NH 1
What is it?
.PP
\fBSWFPut\fP is a plugin for
\fIWordPress\fP.
It provides video player programs
for the flash plugin and and the HTML video
element,
and the means to configure
the players with video sources and playback
attributes.
There are two separate components:
the video players, and the \fIWordPress\fP
plugin proper.
The video players are delivered to site visitors
by the plugin in either an <object ...>
block with a nested <video ...> element as
fallback content, or inversely as a primary
<video ...> with a nested <object ...>
for flash fallback. The former arrangement
is the default at present, and there is an
option to enable the latter arrangement.
It is not necessary to provide for both
types, one or the other type may be left out.
.PP
Video
objects may be placed in posts and pages, or in
the widget areas supported by your theme (i.e.,
the plugin includes a widget).
Video is placed in posts and pages with a
\fIshortcode\fP; if you do not know what a
shortcode is, or do not want to deal with them,
that's no problem.
(In fact, it is preferable that the shortcodes
\fInot\fP be hand-edited, and they will not
be discussed in detail here.) The plugin adds to
the post/page editor interfaces a full featured
form to setup and add, or edit, or delete
video objects, so the user does not need
to be troubled with shortcodes (they will be visible
in the editor; you will get used to them).
The video widget has a similar full
featured form.
.PP
The plugin does not depend on \fIJavaScript\fP,
although it is used for the HTML5 video player,
and for proper resizing of the video display area.
If \fIJavaScript\fP is not available, HTML5
video will have the interface provided by the
web browser, and the flash video will be
largely unaffected (it only uses \fIJavaScript\fP
to check whether it is running on a mobile platform).
Display resizing will not be possible if
\fIJavaScript\fP is not available, so reasonable
dimensions should be given in the setup form.
.PP
The \fBSWFPut\fP flash video player has been
coded to work well with the free \fIGnash\fP
web browser plugin, as well as the closed
binary-only proprietary version in common use.
As of this writing, \fIGnash\fP
does not handle \fBMP4\fP files well, even though
it handles H\.264 video and AAC audio if they
are in an FLV container file. Therefore, it is
a good idea to prepare FLV files for flash if
you can.
\
.NH 1
Building From the Source
.PP
\fBSWFPut\fP is distributed from the
\fIWordPress\fP plugin repository
as a \fIZIP\fP
archive ready for installation on a
\fIWordPress\fP site.
Therefore, there is no need to build the
plugin before use.
.PP
(You may skip forward to the
\fBUsage\fP section if you don't intend
to modify the player or plugin.)
.PP
All necessary sources are included in the
distributed archive, but the necessary
build tools are not. The plugin is maintained
with a POSIX makefile, which in turn
expects a POSIX Bourne shell. Additionally,
the \fIPHP\fP commandline interface with the
\fIMing\fP extension
to build the flash video player,
\fIPERL\fP packages to minify \fIJavaScript\fP,
\fIGNU\fP gettext for localization sources,
\fIGNU\fP groff (and a small C program) to
make the forms of this document, the portable
\fIInfo-ZIP\fP zip command to make the archive,
and various POSIX tools such as sed.
.PP
The actual plugin is composed of
\fIPHP\fP code, and does not
require compilation or link editing.
The flash video player is a compiled program,
but a binary is included in the installable
package so that use does not require
compilation by the user.
.PP
The Makefile default target
builds as necessary and then creates the
ZIP file.
The Makefile is the build documentation.
\
.NH 1
Usage
.PP
\fBSWFPut\fP installs an item
under the \(lqSettings\(rq menu named
\(lqSWFPut Plugin\(rq. Selecting that should
produce the plugin's configuration page.
The configuration page includes optional verbose
help, and so it will not be described here.
.PP
In the post and page editors,
the plugin adds an interactive
form in a new metabox with the title
\(lqSWFPut Video\(rq.
Directly under the title is a row of buttons.
Under the row of buttons, the bulk of the
form is placed in three sections entitled
\(lqMedia\(rq, \(lqDimensions\(rq, and
\(lqBehavior\(rq.
The title bar of each section has a button
that will hide or show that section, which
might help if the height of the form is
greater than that of the display.
.PP
.RS
.NH 2
Form Buttons
\" .RS
.IP \(bu
\fBFill from post\fP:
When the post (or page) already contains
a \fBSWFPut\fP
video object (i.e., shortcode),
this will find it in the
editor and fill the form with its details.
A post may contain any number of
\fBSWFPut\fP video objects. If there
is more than one, then repeatedly
using this button will cycle through
each in turn.
.IP \(bu
\fBReplace current in post\fP:
When the form has been filled with
the details of a video object using
\(lq\fBFill from post\fP\(rq (described
above), or if it contains the details
of a new video object that has just been
added, the form items may be changed, and
this button will edit the associated
shortcode with the changes.
.IP \(bu
\fBDelete current in post\fP:
As described above for
\(lq\fBReplace current in post\fP\(rq,
except that rather than changing
the details of the shortcode, it is
deleted.
.IP \(bu
\fBPlace new in post\fP:
After making sure that the cursor
(insertion point) in the editor is
at the desired position, and filling out
the form items, use this button to add
a new shortcode (video).
.IP \(bu
\fBReset defaults\fP:
Except for the \(lqCaption\(rq text
field, all form items are set to
default values, or cleared. It is
assumed that text typed into
the \(lqCaption\(rq field would be better
maintained by hand, so that field is
not cleared.
\" .RE
\
.NH 2
Form Sections
\" .RS
.NH 3
Media
.IP \(bu
\fBCaption\fP:
A video object is set in a page as
an image would be, with the same border,
and an optional caption, which may be set
here. If this field is left blank, there
will be no caption.
.IP \(bu
\fBFlash video URL or media library ID\fP:
A video URL may be given here,
or an attachment ID valid for the
\fIWordPress\fP database.
Or more conveniently,
this field may be set from the two
drop-down lists described next.
Acceptable protocols are \fIHTTP\fP,
\fIHTTPS\fP, and \fIRTMP\fP.
Support for \fIRTMP\fP is only
partial and very limited. See
\(lq\fBPlaypath (rtmp)\fP\(rq
below. Acceptable file (media) types
are \fBFLV\fP, \fBMP4\fP.
\
.IP \(bu
\fBSelect flash video URL from uploads directory\fP:
This is a drop-down list from which
the URL
field may be set. The \fIWordPress\fP
\f(CRuploads\fR directory is searched
recursively for files with the suffixes
\fBFLV\fP, \fBMP4\fP,
and
for each a URL is added to this list.
This has the advantage that it will find
files added by hand upload (rather than with
the `add media' interface) if they are
placed in \f(CRuploads\fR or a
directory under it.
.IP \(bu
\fBSelect ID for flash video from media library\fP:
This is a drop-down list from which
the URL
field may be set, as above, with the
difference that it searches the
\fIWordPress\fP media database, and
presents the suitable filenames
with their media IDs.
.IP \(bu
\fBHTML5 video URLs or media library IDs\fP:
A series of URLs
for the HTML5 video player.
If more than one URL is given, they should be separated
by the `\f(CR|\fR' (pipe) character. Each individual
URL may be appended with an argument for the
`\f(CRtype\fR' attribute of the video element,
separated from the URL by a `\f(CR?\fR'
character (do not include the `\f(CRtype\fR'
keyword; give only the value that should appear
between quotes in the type argument,
and although many web examples
show a space after the comma separating the video and
audio codec names, \fBFirefox\fP up to at least version 16
will reject the source because of the space, so it should
be left out)\**.
.FS
For example:
.br
\f(CRvideos/cat.mp4?video/mp4|
videos/cat.webm?video/webm; codecs=vp8,vorbis|
videos/cat.ogv?video/ogg; codecs=theora,vorbis\fR.
.FE
If more than one is given they will appear in order.
The browser should use the first type
that it supports (if any, and some older versions
of browsers might not consider any source
but the first to appear). The MP4, WEBM, and OGG
types have varied support among web browsers,
so ideally all three formats should be provided.
.IP \(bu
\fBSelect HTML5 video URL from uploads directory\fP:
(See next item below.)
.IP \(bu
\fBSelect ID for HTML5 video from media library\fP:
These selection items work much like the similarly
named items pertaining to flash URLs, as described
above. These show files with MP4 or OGG or OGV
or WEBM extensions, suitable for the HTML5 video
player. An important difference is that
when you make a selection, the entry field
is appended, rather than replaced,
on the assumption that you are adding
multiple resources for the necessary
HTML5 video formats. When the URL field content
is appended, a `\f(CR|\fR' (pipe) character
is used as a separator. See
\(lqHTML5 video URLs or media library IDs\(rq
above.
.IP \(bu
\fBPlaypath (rtmp)\fP:
If the URL
field for flash video
is given an \fBRTMP\fP URL, the `playpath'
is given here. Note that only the simplest
RTMP connections are supported: those
requiring only the playpath. This item has
bearing on HTML5 video.
.IP \(bu
\fBUrl of initial image file (optional)\fP:
An \fBHTTP\fP or \fBHTTPS\fP URL for an
image file may be placed here. When the player
is loaded, if it is not set to play on load,
this image is displayed until the play
button is invoked. Accepted image types are
\fBJPEG\fP, \fBPNG\fP, and \fBGIF\fP.
.IP \(bu
\fBLoad image from uploads directory\fP:
This is a drop-down list from which
the \(lq\fBUrl of initial image file (optional)\fP\(rq
field may be set. The \fIWordPress\fP
\f(CRuploads\fR directory is searched
recursively for files with the suffixes
listed as acceptable for that field,
and
for each a URL is placed in this list.
This has the advantage that it will find
files added by hand upload (rather than with
the `add media' interface) if they are
placed in \f(CRuploads\fR or a
directory under it.
.IP \(bu
\fBLoad image ID from media library\fP:
This is a drop-down list from which
the \(lq\fBUrl of initial image file (optional)\fP\(rq
field may be set, as above, with the
difference that it searches the
\fIWordPress\fP media database, and
presents the suitable filenames with
their media IDs.
.IP \(bu
\fBUse initial image as no-video alternate\fP:
If an initial image was given, then also use
it as fallback display when video is not
supported. This option is on by default.
\
.NH 3
Dimensions
.IP \(bu
\fBPixel Width \(mu Height\fP:
set these to the desired size of the
video player's embedded window.
This does not need to be the same
as the display size of the video to be played,
but the appearance will be best if the \fIaspect\fP
of the player's display is the same as the
display aspect of the video. For example,
if set for a video with a size of 400\(mu300,
then setting these to fields to 320\(mu240
would look good (the width:height ratio is the
same). In any case, the player will scale the
video to fit within its display, but it maintains
the aspect ratio, so horizontal or vertical
black (unused) areas will be visible if the
aspect ratios do not match.
These dimensions are not fixed unless scripts
are disabled. Where scripting is available,
the video display area is resized in concert
with changes that the browser applies to the
surrounding elements. This is particularly
important on mobile platforms, where the browser
will probably make extreme size adjustments
for the small display size (This behavior might
depend on the current theme). 
.IP \(bu
\fBMobile width\fP:
This is to provide a width to use only
if a mobile browser is detected; the height is automatically
proportional, according to the regular
\(lq\fBPixel Width \(mu Height\fP\(rq
dimensions described above. This might
be used for widgets placed on the sidebar, because the
sidebar might be placed below, rather than beside, the main
content. In this case more space might be available, and
larger display might be suitable. This feature is disabled
with a value of '0,' which is the default, and has no effect
if the browser is not identified as being on a mobile platform.
.IP \(bu
\fBAuto aspect\fP:
This enables a feature meant to be helpful
when the video to be played might have been
prepared as DVD-Video (NTSC or PAL) for
standard (non-widescreen) 4:3 display. Such
video has non-square pixels; i.e., its
actual width\(muheight does not match its
intended display aspect. With this check
enabled, the video player will force display
at 4:3 ratio if the video dimensions match
one of the DVD-Video pixel sizes. This is
not suitable for widescreen DVD-Video, which
has one of the expected DVD-Video pixel sizes, but
is meant to be displayed with a 16:9 aspect.
.IP \(bu
\fBDisplay aspect\fP:
Set the intended display aspect ratio in this
field if you know that the video has non-square
pixels. A value of 0 (zero) disables this field;
otherwise, a value may be given as a decimal
number (e.g., 1.33333333) or as a ratio using
`:' or `x' or `/' as separator (e.g., 4:3,
or 16x9, or 20/11, etc.\(emseveral other characters
will also be accepted as a separator, but it's
sensible to use those listed here).
.IP \(bu
\fBPixel aspect\fP:
Similar to \(lq\fBDisplay aspect\fP\(rq
above, but this field takes the source
(pixel) aspect ratio rather than the display
aspect in the unlikely event that that
value is more readily available. For example,
video prepared for NTSC DVD at 720\(mu480
pixels intended for standard (4:3) display
has a pixel aspect ratio of 8:9, and at
352\(mu240 a pixel aspect ratio of 10:11.
As above, `0' disables this field.
\
.NH 3
Behavior
.IP \(bu
\fBInitial volume\fP:
The video player has a volume control
that visitors can adjust, but this
field will set a default volume. If
the web browser flash plugin is permitted
to save values locally on a visitor's
machine, then their adjustment will be
saved, and will be used rather than the default
when they visit again (or reload the
page). User settings are not saved for the
HTML5 video player presently.
.IP \(bu
\fBPlay on load\fP:
This will cause the video
to begin playing as soon as the
player program is loaded. When this
is not set, the player waits for the
play button. (Above, it was stated
that if scripting is not available,
HTML5 video would have the default
appearance and behavior provided by
the web browser. This play on load
option will not be in effect in that
case, because while the video element
can take an autoplay attribute, that
cannot work the scripted HTML5 player.)
.IP \(bu
\fBLoop play\fP:
This will cause the medium to play again
from the beginning each time it ends.
When this is not set, the video plays
once, and then pauses.
.IP \(bu
\fBHide control bar initially\fP:
This will cause the control bar to
hide a few seconds after the player
loads (e.g., so that it does not
obscure an initial image). Note that
this also changes the control bar
behavior in general: the bar will show
whenever mouse movement is detected
within the embedded window, and hide
again when there has been no mouse
movement for a few seconds.
When this is not set, the control
bar is left showing when the player
loads, and thereafter is always
shown when the mouse is within the
embedded window, and is always hidden
when the mouse is \fIdetected\fP
leaving the window (when the mouse
is moved out of the player window
with rapid motion the browser or plugin
often fails to deliver a `mouse has left'
event to the player program, so hiding
the bar is not always reliable).
.IP \(bu
\fBHide and disable control bar\fP:
Enable this if the media should play
through without interruption.
.IP \(bu
\fBAllow full screen\fP:
This enables a control bar button that
will place the video in full-screen
mode.
.IP \(bu
\fBControl bar Height (30-60)\fP:
The control bar height can be adjusted
with this. The range 30-60 merely suggests
useful sizes; it is not a fixed boundary.
A good size would be influenced by
the specified display dimensions on
non-mobile platforms, but also by
usability on mobile platforms. Test, please.
\
\" .RE
.RE
\
.NH 2
The Widget
.PP
The player can also be used as a widget.
The \(lqAppearance\(rq menu
\(lqWidgets\(rq item should produce the
\(lqWidgets\(rq page which, after installation
of \fBSWFPut\fP, should show
\(lq\fBSWFPut Video Player\fP\(rq under
\(lq\fBAvailable Widgets\fP\(rq. After dragging
this to a widget area the setup form
should display (click the arrow near
the title if necessary). The widget's
form has the same items described under
\(lq\fBForm Sections\fP\(rq above, although
this form is not displayed in the three
separate sections and does not have the
buttons near the top.
There is one additional
item at the top of the widget form: a
text field named \(lqWidget title\(rq.
Not surprisingly, the contents of that
field will be displayed as a title
above the widget on the pages that
include the particular widget area used.
\
.NH 1
License
.PP
This program and all files included in
the distribution archive are under the
\f(BIGNU GPL\fP, version 3.
See the file \f(CRCOPYING\fP, which
should be present in the top-level
directory of the distribution archive;
or, see the license at
\f(CRhttp://www.gnu.org/licenses/\fP.
\
\".TC