Copyright (c) 2002-2018 Xiph.org Foundation
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
- Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
- Neither the name of the Xiph.org Foundation nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION
OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
（2）webmdshow - readme
WebM Project DirectShow Filters
The WebM Project DirectShow Filters package ("webmdshow") allows you to
encode and decode VP8 video (and decode VP9 video), encode and decode
Vorbis audio, and write and read WebM files, all using Microsoft DirectShow.
A website has been set up to host artifacts associated with the WebM
The actual download page is here:
Some mailing lists have been set up to discuss WebM-related issues.
The main page is here:
That page has instructions for subscribing to the lists. The actual
lists are hosted here:
If you find a bug, or there's a feature you want, then please file a
report using the WebM issue tracking system:
You can browse existing issues here:
You can create a new issue here:
If you are a developer and would like to build from sources, then
you can use Git to clone the origin, like this:
git clone git://review.webmproject.org/webmdshow.git
A DirectShow filter is a "COM InProc Server DLL", and so it needs to be
registered with the system. The delivery artifacts should include a file
named "install_webmdshow.exe". Run that installer (either from a command
prompt, or from a Windows Explorer shell) and it will automatically
register the filters on your system. The DLLs are placed in the following
C:\Program Files\Common Files\WebM Project\webmdshow
To uninstall, you can choose the uninstall option from the Add or Remove
Programs control panel, or run the uninstall_webmdshow.exe in the install
directory listed above.
The webmdshow package also includes a couple of simple command-line
utilities for reading and writing WebM files, that are implemented using the
Webm DirectShow filters. The utility PLAYWEBM (playwebm.exe) is for basic
testing and playback of WebM files, and the utility MAKEWEBM (makewebm.exe)
is for simple creation of WebM files. They are not automatically installed
by the installer, so if you'd like to use them, just extract them from the
archive and place them in your path.
Description of Microsoft DirectShow and the WebM DirectShow Filters
Microsoft DirectShow is a framework for manipulation of media streams on
Windows. Streams are constructed from "filters" that are connected via
"pins". You mix and match different kinds of filters in order to construct
a stream having the characteristics you desire.
A WebM file is a container for a video stream encoded as VP8, and an audio
stream encoded as Vorbis. The file itself uses the ".webm" file extension.
The file format is a subset of the Matroska container format, with "webm"
as the DocType.
In order to play back WebM files in a DirectShow-based media player (such
as Windows Media Player), you need a "source" filter that understands the
format of the file, and "decoder" filters for each stream.
When a media player attempts to render a file using DirectShow, it looks
at the file extension to determine whether a source filter has been
specifically associated with that extension. When the WEBMSOURCE filter
(webmsource.dll) is installed, it registers itself as the source filter
for ".webm" files, so if things are working normally, an instance of that
source filter will be created automatically by the DirectShow graph builder,
and the filter will then load the file.
(Note that this association of a file extension with a DirectShow source
filter is distinct from the association of a file extension with a
rendering application. The former is controlled by DirectShow, and the
latter by the Windows shell.)
The source filter exposes as many output pins as there are streams in the
WebM file. This will typically be one VP8 video stream (or possibly one VP9
video stream) and one Vorbis audio stream. The WebM VP8DECODER filter
(vp8decoder.dll) decodes the VP8 video stream, which should be all you need
for video rendering. The WebM VORBISDECODER filter (webmvorbisdecoder.dll)
decodes the Vorbis audio stream.
The WEBMMUX filter (webmmux.dll) creates ("multiplexes") WebM files. It
accepts a VP8-encoded video input stream and a Vorbis-encoded audio input
stream. The VP8ENCODER filter (vp8encoder.dll) is used to encode the video,
and is connected directly to the WEBMUX filter.
The WEBMVORBISDECODER filter (webmvorbisdecoder.dll) decodes the Vorbis audio
track in the WebM file, and the WEBMVORBISENCODER (webmvorbisencoder.dll)
encodes Vorbis audio.
You can also try the filters available here:
Playing WebM Files on Windows using DirectShow
Once you have installed the WEBMSOURCE filter, VP8DECODER filter, and
a Vorbis decoder filter, then you should be able to play WebM files in
any DirectShow-based media player, such as Windows Media Player.
If you're familiar with DirectShow, you can also build filter graphs
using GraphEdit or GraphStudio. (GraphEdit is part of the Windows SDK.)
The friendly-name of each filter begins with "WebM", so they're listed
all together in the filter list dialog.
The webmdshow package also includes a command-line application called
PLAYWEBM (playwebm.exe) for simple playback of WebM files. In particular
it is useful for determining whether the necessary DirectShow filters
for rendering WebM files have been installed on your system. If you
can successfully play back the WebM file using PLAYWEBM, then that
usually indicates that the file can be played back by any other
DirectShow-based media player.
The PLAYWEBM command-line swiches can be specified using either short-form
(single hyphen) or long-form (double hyphen) syntax. Long forms are
case-insensitive and may be abbreviated. Long forms can also be specified
using Windows-style (forward slash) syntax.
If you need help, use the --help (or -h) switch, or simply run the
app without specifying any arguments. For more detailed information,
use the --help switch in combination with the --verbose (or -v) switch.
The WebM input file can be specified as the (only) command-line argument,
or as the value of the --input (or -i) switch. If you do not specify
any other switches, PLAYWEBM uses IGraphBuilder::RenderFile to build the
graph automatically. This most closely mimics what other, more general
DirectShow-based players do to render an arbitrary file (so it's a good
test of whether your system has been configured correctly).
If you use the --source (or -s) switch, PLAYWEBM will explicitly create
an instance of the WEBMSOURCE filter, load the file using that filter,
and then render each output pin.
With the --splitter (or -S) switch, PLAYWEBM will load the file using
the AsyncReader filter, explicitly create an instance of the WEBMSPLIT
filter, connect the two filters and then render each output pin.
If you specify the --list (or -l) switch, the app will print the values
of the command-line arguments, and then immediately terminate. With the
--verbose (or -v) switch also specified, the app expands the input file
name to its full path value.
Whenever you're in doubt, always try the --list and --verbose options
together, to verify that PLAYWEM has interpreted the command-line
argument values as you have intended.
The --version (or -V) switch is used to print the value of the
app's version. If you have a problem with PLAYWEBM, please include
the app's version value in your bug report.
Authoring WebM Files On Windows Using DirectShow
The webmdshow package includes a VP8 encoder filter and a WebM muxer
filter, which enable you to create WebM files by transcoding files
that are formatted or encoded differently. (A Vorbis encoder filter
is also available from Xiph.org, as explained above.)
The package also includes basic utility, MAKEWEBM (makewebm.exe),
that uses those filters to create WebM files. If you have all the
requisite filters for parsing input files and decoding streams,
then the application should just work. Specify the name of the
input file on the command-line and MAKEWEBM will make a WebM file
with the same basename but with extension ".webm", like this:
$ makewebm xyz.avi
This creates file xyz.webm.
The MAKEWEBM app has a few command-line switches to modify its
behavior. The switches are described here, but you can always
get the list by running MAKEWEBM without any arguments, or by
specifying the --help (or -h) switch.
Switches can be specified using short-form syntax (preceded by
a single hypen), long-form syntax (preceded by a pair of hyphens),
or using Windows-style syntax (preceded by a forward slash).
Switches and arguments and can be specified in any order. Switches
can be abbrievated, and long-form options are case-insensitive.
The value for long-form switches can be specified as part of the
switch itself by separating the switch from the value using an
equal sign. If no equal sign is present, then the value stands
by itself as the next command-line argument. For example:
makewebm --input=XYZ.AVI ...
makewebm --input XYZ.AVI ...
The value for Windows-style switches can be specified as part of
the switch itself by separating the switch from the value using
a colon. If no colon is present, then the value stands by itself
as the next command-line argument. For example:
makewebm /input:XYZ.AVI ...
makewebm /input XYZ.AVI ...
Short-form switches that accept a value require that the value
appear as the next command-line argument. The reason is that you're
allowed to use a long-form spelling for some switches, for example:
makewebm -i XYZ.AVI ...
makewebm -input XYZ.AVI ...
Where there is ambiguity among switches (e.g. "/ver"), the precedence
of switches is determined by their order in the help (usage) display.
MAKEWEBM requires that the input filename be specified. The input file
can be specified using the --input (or -i) switch, or as the (first)
The output file can specified using the --output (or -o) switch,
or as the (second) argument. This names the resulting WebM file.
If you don't specify the output filename value explicitly, its value
is synthesized from the input filename value. So the following commands
are all equivalent:
makewebm -i xyz.avi -o xyz.webm
makewebm -i xyz.avi xyz.webm
makewebm xyz.avi -o xyz.webm
makewebm xyz.avi xyz.webm
makewebm -i xyz.avi
MAKEWEBM only transcodes input streams if they aren't encoded as
VP8 (for video) or Vorbis (for audio). If a stream already has
that encoding, then it is connected directly to the WEBMMUX filter
as is, without being re-encoded.
If MAKEWEBM needs to encode to Vorbis audio, and it cannot find a
filter to perform the encoding, then by default it will make a
WebM file without audio. If you want the app to terminate if it
cannot also encode the audio stream, then specify the
The --list (or -l) switch will print the values of the command-line
arguments and switches, without building the actual graph. If you
also specify the --verbose (or -v) switch, the input and output
filenames are expanded to their full paths.
If you specify the --verbose (or -v) switch (without also specifying
the --list switch), then as the graph is being built the app prints
the media subtype and format of the pins being connected. This is
helpful for determining exactly how the input streams are encoded.
The --version (or -V) switch prints the value of the app's version
resource. If you submit a bug report, please include the version
value of your copy of the MAKEWEBM app in your report.
By default, while MAKWEBM is running, it prints the progress of the
mux by over-writing the same line on standard output. (The value
it writes is the current position in the output file, expressed as
time, in units of seconds.) This behavior can be changed by
specifying the --script-mode switch, which causes progress to be
written to standard output on a new line each time, and in a format
that is easily parseable. This switch is intended to be used when
MAKEWEBM app is being called from within a script that is capturing
text written to standard output by the app. See the comments at
the top of the script VBSMAKEWEBM.VBS that accompanies the delivery
artifacts for an example of how to use this option.
The VP8ENCODER filter (vp8encoder.dll) has a custom IDL-based interface
that enables you to configure the encoding. MAKEWEBM includes several
command-line switches that allow you to manipulate the VP8ENCODER
filter. Run the MAKEWEBM app with the --help switch to get a complete
list of switches. The switches for VP8 encoding match the method names
in the IDL file for the VP8 encoder. See the file "vp8encoder.idl"
among the delivery artifacts (it's in the IDL folder of the source
tree) for a full description of each configuration parameter.
VP8 Encoder Filter Notes
The VP8 encoder filter (as with the VP8 encoder library) only accepts
YUV formats as input. If you have a file or capture device with
RGB as output, you'll need the WEBMCC filter to convert from RGB to YUV.
(The ffdshow filter will also do such a conversion, but it might be disabled
by default. To enable it, open the Properties page for the ffdshow
Video Decoder filter, and under the Codecs menu, find the Raw video item.
Change the Decoder option so that it's not "disabled" (the values
"all RGB" or "all supported" both seem to work), and then an instance
of that filter will be created automatically when RGB-to-YUV conversion
The VP8 encoder also has a property page, so if you're using GraphEdit
or similar you can modify encoder settings that way. It works as follows.
The filter has a settings cache. When you make a change to a settings
value (via the IVP8Encoder interface), this actually changes the value in
the cache. If the graph is stopped, then the settings are applied only
later (and automatically), during the transition from stopped to paused or
running. If the graph is not stopped (and you're using the IDL interface
directly), then you must apply the settings by calling
IVP8Encoder::ApplySettings. The only settings that are actually applied
are those settings that have a value that is not "out-of-band", which
typically means equal or greater than 0. For settings that haven't been
set (the cached setting still has its default out-of-band value, -1), then
the encoder uses the default supplied by the vpx encoder library itself.
When the property page is first loaded, it queries the cache and displays
any non-default settings. Edit controls and combo boxes for settings
that have a default value are left blank. When you click on the OK or
Apply buttons, the property page modifies the cache settings that
correspond to controls with non-empty values.
The Clear button on the property page dialog window simply clears
all of the edit controls. If you were to Apply the values on the
page in this state it would have no effect, because there are no controls
with non-empty values. This is useful if you want to selectively change
a value without disturbing values that already exist in the cache.
The Reload button re-initializes the controls on the dialog window, the
same as if the property page had been dismissed via the Cancel button
and then immediately re-created. This is useful if you've made changes
to the dialog but decide to throw the values away and start over.
The Reset button calls IVP8Encoder::ResetSettings to re-initialize
all of the settings in the cache to their default (out-of-band) values,
and sets the controls to empty values. This has the effect of throwing
away settings in the cache and starting over.