SWFPut -- Flash and HTML5 Video Plugin for Word-
Press
Ed Hynan
This `README' serves as the main documenta-
tion for the SWFPut WordPress plugin, and as the
conventional `README' as well.
1. What is it?
SWFPut is a plugin for WordPress. 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 WordPress 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 pre-
ferred. It is not necessary to provide for both types, one
or the other type may be left out.
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 shortcode; 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 not 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 inter-
face similar to that used by WordPress core media, and also
a full featured form in a "metabox" 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.
Video in posts may be displayed in the WordPress 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 SWFPut settings page.
-2-
SWFPut does not depend on JavaScript on the front end,
but it is used for the HTML5 video player, and for proper
resizing of the video display area. If JavaScript is not
available, HTML5 video will have the interface provided by
the web browser, and the flash video will be largely unaf-
fected (it only uses JavaScript to check whether it is run-
ning on a mobile platform). "Responsive" display resizing
will not be possible if JavaScript is not available, so rea-
sonable dimensions should be given in the setup form.
The SWFPut flash video player has been coded to work
well with the free Gnash web browser plugin, as well as the
closed binary-only proprietary version in common use. As of
this writing, Gnash does not handle MP4 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 pre-
pare FLV files for flash if you can.
2. Building From the Source
SWFPut is distributed from the WordPress plugin reposi-
tory as a ZIP archive ready for installation on a WordPress
site. Therefore, there is no need to build the plugin
before use.
(You may skip forward to the Usage section if you don't
intend to modify the player or plugin.)
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 PHP
command-line interface with the Ming extension to build the
flash video player, PERL packages to minify JavaScript, GNU
gettext for localization sources, GNU groff (and a small C
program) to make the forms of this document, the portable
Info-ZIP zip command to make the archive, and various POSIX
tools such as sed.
The actual plugin is composed of PHP 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.
The Makefile default target builds as necessary and
then creates the ZIP file. The Makefile is the build docu-
mentation.
-3-
3. Usage
SWFPut installs an item under the "Settings" menu named
"SWFPut Plugin". Selecting that should produce the plugin's
configuration page. The configuration page includes
optional verbose help, and so it will not be described here.
In the post and page editors, the plugin adds a button,
labelled "Add SWFPut Video," next to the "Add Media" 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.
SWFPut also adds an interactive form in a new metabox
with the title "SWFPut Video". This form has advanced set-
tings 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
"Media", "Dimensions", and "Behavior". The title bar of
each section has a button that will hide or show that sec-
tion, which might help if the height of the form is greater
than that of the display.
3.1. Form Buttons
o Fill from post: When the post (or page) already
contains a SWFPut 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 SWFPut video objects. If there is more than
one, then repeatedly using this button will cycle
through each in turn.
o Replace current in post: When the form has been
filled with the details of a video object using
"Fill from post" (described above), or if it con-
tains 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.
o Delete current in post: As described above for
"Replace current in post", except that rather than
changing the details of the shortcode, it is
deleted.
o Place new in post: After making sure that the cur-
sor (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).
-4-
o Reset defaults: Except for the "Caption" text
field, all form items are set to default values,
or cleared. It is assumed that text typed into the
"Caption" field would be better maintained by
hand, so that field is not cleared.
3.2. Form Sections
3.2.1. Media
o Caption: 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.
o Flash video URL or media library ID: A video URL
may be given here, or an attachment ID valid for
the WordPress database. Or more conveniently,
this field may be set from the two drop-down lists
described next. Acceptable protocols are HTTP,
HTTPS, and RTMP. Support for RTMP is only partial
and very limited. See "Playpath (rtmp)" below.
Acceptable file (media) types are FLV, MP4.
o Select flash video URL from uploads directory:
This is a drop-down list from which the URL field
may be set. The WordPr_ss uploads directory is
searched recursively for files with the suffixes
FLV, MP4, 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
uploads or a directory under it.
o Select ID for flash video from media library: This
is a drop-down list from which the URL field may
be set, as above, with the difference that it
searches the WordPress media database, and
presents the suitable filenames with their media
ID's.
o HTML5 video URLs or media library ID's: A series
of URLs for the HTML5 video player. If more than
one URL is given, they should be separated by the
`|' (pipe) character. Each individual URL may be
appended with an argument for the `type' attribute
of the video element, separated from the URL by a
`?' character (do not include the `type' 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
-5-
reject the source because of the space, so it
should be left out)1. 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.
o Select HTML5 video URL from uploads directory:
(See next item below.)
o Select ID for HTML5 video from media library:
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 `|' (pipe) character is used as a sep-
arator. See "HTML5 video URLs or media library
ID's" above.
o Playpath (rtmp): If the URL field for flash video
is given an RTMP 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.
o Url of initial image file (optional): 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 but-
ton is invoked. Accepted image types are JPEG,
PNG, and GIF.
o Load image from uploads directory: This is a drop-
down list from which the "Url of initial image
file (optional)" field may be set. The WordPress
uploads 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
uploads or a directory under it.
-----------
1 For example:
videos/cat.mp4?video/mp4|
videos/cat.webm?video/webm; codecs=vp8,vorbis|
videos/cat.ogv?video/ogg; codecs=theora,vorbis.
-6-
o Load image ID from media library: This is a drop-
down list from which the "Url of initial image
file (optional)" field may be set, as above, with
the difference that it searches the WordPress
media database, and presents the suitable file-
names with their media ID's.
o Use initial image as no-video alternate: If an
initial image was given, then also use it as fall-
back display when video is not supported. This
option is on by default.
3.2.2. Dimensions
o Pixel Width x Height: 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 aspect of the player's display is
the same as the display aspect of the video. For
example, with a video of a size of 400x300 setting
these to fields to 320x240 would look good, as the
width:height ratios are the same.
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 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 "responsive" behav-
ior will depend on the current theme being respon-
sive.
o Mobile width: This is to provide a width to use
only if a mobile browser is detected; the height
is automatically proportional, according to the
regular "Pixel Width x Height" dimensions
described above.
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
-7-
a mobile platform.
o Auto aspect: 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 stan-
dard (non-widescreen) 4:3 display. Such video has
non-square pixels; i.e., its actual widthxheight
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.
o Display aspect: 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.--several other characters
will also be accepted as a separator, but it's
sensible to use those listed here).
o Pixel aspect: Similar to "Display aspect" 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 720x480 pixels intended for standard (4:3)
display has a pixel aspect ratio of 8:9, and at
352x240 a pixel aspect ratio of 10:11. As above,
`0' disables this field.
3.2.3. Behavior
o Alignment: This is an exclusive selection with
options `left,' `center,' `right,' and `none.'
The default is center. This option will set the
alignment of the video display within the page or
post by adding a CSS class called one of `.align-
left,' `.aligncenter,' `.alignright,' or `.align-
none.' A WordPress theme should provide CSS defi-
nitions for the first three of those classes. The
fourth, .alignnone, is meant to use the alignment
that the video markup inherits, whatever it might
be. (If there is a CSS definition for .alignnone
hopefully it will have a sensible effect.)
Because this option works with classes, which
depend on CSS definitions, it is ultimately the
user's WordPress theme that provide the effect of
this option. For example, if a theme provides a
-8-
left or right margin for the `.widget' class, then
this plugin's video widget might not align accord-
ing to this option.
o Video preload: This is an exclusive selection.
HTML5 video allows a "preload" attribute with a
value of "none" or "metadata" or "auto." This
option provides those three values and one special
selection: "per initial image." This special
selection will use "none" if an "initial image
file" is set (in the Media section of the form),
or "metadata" if an initial image, or poster, is
not set.
The "metadata" selection allows the browser to
fetch a small part of the video file with informa-
tion such as video dimensions, duration, and the
codec types2. 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.)
If "none" is selected the browser will not fetch
any of the video until it is played, and so with-
out an initial image, the video region on the page
will be solid black until played.
The "auto" selection should be avoided unless you
know what it does and that you need it. This is
because with "auto" 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.
The flash player does not have similar attributes,
but will behave similarly with regard to an ini-
tial image: if one was not set, and the preload
option is not "none," 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.'
-----------
2 In most of the supported video file types, the
browser should be able to find the metadata with-
out needing to retrieve too much data.
-9-
o Initial volume: The video player has a volume con-
trol 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.
o Play on load: 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 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.
o Loop play: 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.
o Hide control bar initially: This will cause the
control bar to hide a few seconds after the player
loads (e.g., so that it does not obscure an ini-
tial image). Note that this also changes the con-
trol 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
detected 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).
o Hide and disable control bar: Enable this if the
media should play through without interruption.
-10-
o Allow full screen: This enables a control bar but-
ton that will place the video in full-screen mode.
o Control bar Height (30-60): 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.
3.3. The Widget
The player can also be used as a widget. The "Appear-
ance" menu "Widgets" item should produce the "Widgets" page
which, after installation of SWFPut, should show "SWFPut
Video Player" under "Available Widgets". 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 "Form Sections" 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 "Widget title". 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.
4. License
This program and all files included in the distribution
archive are under the GNU GPL, version 3. See the file
COPYING, which should be present in the top-level directory
of the distribution archive; or, see the license at
http://www.gnu.org/licenses/.