\" 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 HTML video element
and the flash plugin,
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 as either HTML5 video with
a flash plugin program as
fallback content, or inversely as flash video
primary content with HTML5 video elements
for fallback. The former arrangement
is the default (as of version 2.1), but there is an
option to enable the latter arrangement
if flash is preferred.
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 button to insert video at the cursor,
and an easy to use dialog-type setup interface
similar to that used by \fIWordPress\fP
core media, and also
a full featured form in a \(lqmetabox\(rq
with additional advanced settings
to setup and add, or edit, or delete
video objects.
The video widget has a similar full
featured form for setup.
.PP
Video in posts may be displayed in the
\fIWordPress\fP visual editor, if the
default visual editor is used. If the
default visual editor has been changed,
for example by a plugin, the video display
in the editor
will probably not work. If there are problems,
video display in the editor may be disabled
on the \fBSWFPut\fP settings page.
.PP
\fBSWFPut\fP does not depend on \fIJavaScript\fP
on the front end,
but 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).
\(lqResponsive\(rq 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.
Additional requirements are
the \fIPHP\fP command-line 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 a button, labelled
\(lqAdd SWFPut Video,\(rq next to the
\(lqAdd Media\(rq button. This will
insert a placeholder video at the cursor
position. When selected, a pencil button
will appear, which invokes a graphical
setup dialog. This dialog is expected
to be easy and intuitive, so it is
not elaborated on here.
.PP
\fBSWFPut\fP also adds
an interactive
form in a new metabox with the title
\(lqSWFPut Video\(rq. This form has
advanced settings not available in
the graphical dialog.
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 ID's.
.IP \(bu
\fBHTML5 video URLs or media library ID's\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, browsers might
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. 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 ID's\(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:
A URL for a `poster'
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 ID's.
.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,
with a video of a size of 400\(mu300
setting these to fields to 320\(mu240
would look good, as the width:height ratios are the
same.
.IP
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.
.IP
These dimensions are not fixed unless scripts
are disabled in the browser.
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 \(lqresponsive\(rq behavior will
depend on the current theme being responsive. 
.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.
.IP
This might be most useful for
widgets placed on a `sidebar,' because a
sidebar might be placed below, rather than beside, the main
content. In this case more effective
display width might be available, and
a wider display might be suitable.
This feature is disabled
with a value of '0,' which is the default,
and has no effect
if the browser provides a user agent string
not known as 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
\fBAlignment\fP:
This is an exclusive selection with options
`left,' `center,' `right,' and `none.'
The default is \fIcenter\fP.
This option will set
the alignment of the video display within
the page or post by adding a CSS class
called one of
`.alignleft,' `.aligncenter,'
`.alignright,' or `.alignnone.'
A \fIWordPress\fP theme should provide
CSS definitions for the first three of
those classes. The fourth, .\fIalignnone\fP,
is meant to use the alignment that the
video markup inherits, whatever it might be.
(If there is a CSS definition
for .\fIalignnone\fP hopefully it will
have a sensible effect.)
.IP
Because this option works with classes,
which depend on CSS definitions, it is
ultimately the user's \fIWordPress\fP
theme that provide the effect of this option.
For example, if a theme provides a left or right
margin for the `.widget' class, then this plugin's
video widget might not align according to this
option.
.IP \(bu
\fBVideo preload\fP:
This is an exclusive selection.
HTML5 video allows a \(lqpreload\(rq attribute
with a value of \(lqnone\(rq
or \(lqmetadata\(rq or \(lqauto.\(rq This option
provides those three values and one special selection:
\(lqper initial image.\(rq This special selection will use
\(lqnone\(rq if an \(lqinitial image file\(rq
is set (in the \fBMedia\fP
section of the form), or \(lqmetadata\(rq if an initial
image, or \fIposter\fP, is not set.
.IP
The \(lqmetadata\(rq selection allows the browser
to fetch a small part of the video file with
information such as video dimensions,
duration, and the codec types\**.
.FS
In most of the supported video file types, the browser
should be able to find the metadata without needing to
retrieve too much data.
.FE
This can be useful because
a browser might also receive some of the video
frames, and so it may display one frame as a `poster.'
(Whether a
frame displayed this way is suitable is not certain.)
.IP
If \(lqnone\(rq is selected the browser will not fetch
any of the video until it is played, and so without
an initial image, the video region on the page will
be solid black until played.
.IP
The \(lqauto\(rq selection should be avoided unless you
know what it does and that you need it. This is
because with \(lqauto\(rq the browser may choose to
fetch the entire video even before the visitor
actively plays the video. Video files can be
quite large, and a large unsolicited download
might be unkind to your site's visitors; it
might even cause a visitor additional charges
depending on their connection service. Also
consider your server and network load.
.IP
The flash player does not have similar attributes,
but will behave similarly with regard to an
initial image: if one was not set, and the
preload option is not \(lqnone,\(rq then the player
will start playback and let it advance for a
small random period, and then pause playback,
leaving a visible frame to act as a `poster.'
.IP \(bu
\fBInitial volume\fP:
The video player has a volume control
that visitors can adjust. 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.
.IP
Above, it was stated
that if scripting is not available
in the web browser,
HTML5 video will have the default
appearance and behavior provided by
the web browser. The play on load
option will not be in effect in that
case, because while the video element
can take an autoplay attribute, that
cannot reliably work with the scripted
HTML5 player since it might begin before
the script gains control of the
video element.
.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.
.IP
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