C++ C NSIS Shell Visual Basic Assembly Other
WebM Project DirectShow Filters http://www.webmproject.org/ Summary 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. Preliminaries A website has been set up to host artifacts associated with the WebM project: http://www.webmproject.org/ The actual download page is here: http://downloads.webmproject.org/releases/webm/index.html Some mailing lists have been set up to discuss WebM-related issues. The main page is here: http://www.webmproject.org/about/discuss/ That page has instructions for subscribing to the lists. The actual lists are hosted here: http://lists.webmproject.org/ http://groups.google.com/a/webmproject.org If you find a bug, or there's a feature you want, then please file a report using the WebM issue tracking system: http://www.webmproject.org/code/bug-reporting/ You can browse existing issues here: http://code.google.com/p/webm/issues/list You can create a new issue here: http://code.google.com/p/webm/issues/entry 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 Installation 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 directory: 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: http://www.mediacodec.org/ http://xiph.org/dshow/ 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) argument. 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 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 --require-audio switch. 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 is required.) 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.