\" these two registers are probably groff-only
.nr PORPHANS 3
.nr PORPHANS 3
.TL
SWFPut \(em Flash Video Player 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
the popular \fIWordPress\fP
weblog
software. It provides a video player program
for the flash plugin and the means to configure
an instance with a video source and playback
attributes.
There are two separate components:
the flash video player, and the \fIWordPress\fP
plugin proper.
The video player is delivered to site visitors
by the plugin in the traditional <object ...>
block with the necessary arguments. Flash 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 administrative interface 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 flash video widget has a similar full
featured form.
.PP
The plugin does not add any \fIJavaScript\fP
to the pages generated for your visitors,
which might be helpful if you try to keep your
pages useful to those who disable JavaScript
in their browsers. (Such visitors might need
to explicitly enable the flash
web browser plugin, but that
is another, unavoidable, issue.)
JavaScript is used in the administrative
interface for the forms and manipulation
of shortcodes in the editor; but of course
you must have JavaScript enabled when you
log in to your \fIWordPress\fP
site \(em this does not
affect your visitors.
.PP
(Note that the \fBSWFPut\fP 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.)
\
.NH 1
Building From the Source
.PP
\fBSWFPut\fP is distributed as a \fIZIP\fP
archive prepared for installation on a
\fIWordPress\fP site with the \(lqAdd New\(rq
item under the \(lqPlugins\(rq menu.
Therefore, there is no need to build the
package before use.
.PP
(You may skip forward to the
\fBUsage\fP section if you don't intend
to modify the player or plugin.)
.PP
The actual plugin is composed of
\fIPHP\fP code, and JavaScript for
the administrative parts, and neither of those
requires compilation or link editing.
The flash video player is a compiled program,
but binaries are included in the installable
package so that use does not require
compilation by the user. Of course,
the source code is included and the
binaries may be built if necessary
(or desired). Compiling the flash
program will require the \fIMing\fP
PHP extension. See the files
\f(CRMakefile\fR,
\f(CRmingtest/mingput\.php\fR, and
\f(CRmingtest/mainact\.inc\.php\fR
if you wish to learn to build the player.
.PP
If you wish to change the JavaScript code,
edit \f(CRjs/formxed\.dev\.js\fR, rather than
\f(CRjs/formxed\.js\fR.
The latter is merely a `minified' version
of the former; see \f(CRMakefile\fR.
.PP
This file (README*) is built with
the \fIGNU\fP roff
\fIgroff\fP with \fIms\fP macros;
see \f(CRdocs/Makefile\fR.
.PP
The Makefiles require a \fIUnix\fP-like or
\fIPOSIX\fP system. The default target
builds as necessary and then creates the
ZIP file.
\
.NH 1
Usage
.PP
A logged in session is assumed.
.PP
\fBSWFPut\fP installed will add 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
When editing posts or pages,
below the editor
the plugin will have placed an interactive
form with the title
\(lqSWFPut Flash Video Shortcode\(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 the display.
.PP
.RS
.NH 2
Form Buttons
\" .RS
.IP \(bu
\fBFill form from editor\fP:
When the post (or page) already contains
a \fBSWFPut\fP flash
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 editor\fP:
When the form has been filled with
the details of a video object using
\(lq\fBFill form from editor\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 (video object) with the changes.
.IP \(bu
\fBDelete current in editor\fP:
As described above for
\(lq\fBReplace current in editor\fP\(rq,
except that rather than changing
the details of the shortcode, it is
deleted.
.IP \(bu
\fBPlace new in editor\fP:
After making sure that the cursor
(insertion point) in the editor is
at the desired position, and setting
the form items, use this button to add
a new shortcode (video).
.IP \(bu
\fBReset default values\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
\fBUrl or media library ID\fP:
A fully qualified URL may be given here,
or an 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 (video), and
\fBMP3\fP (audio)\**.
.FS
For \fBMP3\fP files, you may try placing
a video URL in the
\(lq\fBPlaypath (rtmp)\fP\(rq field to play
along with the audio. If the video has an
audio stream, that will mix in, so it should
probably be a video only file. This is an
experimental and \fBunsupported\fP
feature.
.FE
\
.IP \(bu
\fBUrl from uploads directory\fP:
This is a drop-down list from which
the \(lq\fBUrl or media library ID\fP\(rq
field may be set. The \fIWordPress\fP
\f(CRuploads\fR directory is searched
recursively for files with the suffixes
\fBFLV\fP, \fBMP4\fP, and \fBMP3\fP,
and
for each a URL is placed in this list.
This has the advantage that it will find
files added by hand (rather than with
the `add media' interface) if they are
placed in \f(CRuploads\fR or a
directory under it.
.IP \(bu
\fBSelect ID from media library\fP:
This is a drop-down list from which
the \(lq\fBUrl or media library ID\fP\(rq
field may be set, as above, with the
difference that it searches the
\fIWordPress\fP media database, and
presents the suitable filenames
their media IDs.
.IP \(bu
\fBPlaypath (rtmp)\fP:
If the \(lq\fBUrl or media library ID\fP\(rq
field
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.
.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, and
\fBSWF\fP\**.
.FS
\fBSWF\fP files may be stills or
animations. This type is a flash
\fIprogram\fP that the flash
web browser plugin
will be executing, so, of course, it must
not interfere with the \fBSWFPut\fP
player. Test thoroughly if this is used.
.FE
.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 (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
their media IDs.
.IP \(bu
\fBMedium is audio\fP:
To determine whether to play video or audio,
the file suffix of the medium is checked.
If the file suffix is not known, the
medium is assumed to be video. If the medium is
an mp3 audio file, but it does not have
the \fBMP3\fP suffix, check this.
\
.NH 3
Dimensions
.IP \(bu
\fBPixel Width \(mu Height\fP:
set these to the desired size of the
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. It is also important
to note that the browser will (probably) honor
a maximum width for a page column set in \fICSS\fP,
and force the browser's flash plugin to display
at a smaller width than the user specified.
For example, if you set these fields to 640\(mu480,
but the column in which posts appear has a width
of 600, the display would be at 600\(mu480. In
such a case, you might try 600\(mu450 to maintain
the aspect so that the video matches display size.
The above assumes a 4:3 aspect; you would use
the correct numbers, of course.
.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, of 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).
.IP \(bu
\fBPlay on load\fP:
This will cause the video (or audio)
to begin playing as soon as the
player program is loaded. When this
is not set, the player waits for the
play button.
.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 media 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 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 (20-50)\fP:
The control bar height can be adjusted
with this. Actually, there is a fixed
number precompiled sizes in the player
binaries that are distributed with
the package, and this field causes the
nearest size to be selected. If the
\fIWordPress\fP host's \fIPHP\fP
configuration includes the \fIMing\fP
extension, then you may select an
option on the \fBSWFPut\fP
configuration page called
\(lqDynamic SWF generation\(rq.
This produces the video player
on the fly, and in this case the
value of this field builds the
control bar at the requested
size rather than using a near match.
\
\" .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 Flash Video\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.
.PP
The description under
\(lq\fBPixel Width \(mu Height\fP\(rq above
mentioned the maximum column widths set by
the theme's CSS, and how the video window
width might be limited by the those.
The same applies to
widget areas, but the maximum width is
likely much less than that in the posts
area. These fields have defaults in the
widget form that have been useful with
the themes distributed with
\fIWordPress\fP, but the user should
certainly do some testing along with
the chosen theme.
\
.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