DATASTEAD SOFTWARE

Multipurpose DirectShow Encoder SDK

version 1.1.2
Last update: March 9, 2015
Copyright 2015 Datastead. All rights reserved.
Overview......................................................................................................................................................3
Features...................................................................................................................................................3
System requirements...............................................................................................................................4
Download.................................................................................................................................................4
License.....................................................................................................................................................4
Contact.....................................................................................................................................................4
Limitations of the evaluation version........................................................................................................4
FAQ..............................................................................................................................................................5
Licensing..................................................................................................................................................5
Evaluation version....................................................................................................................................5
Troubleshooting........................................................................................................................................5
Are transcoders others than FFmpeg supported?...................................................................................6
Does VLC work with the Multipurpose Encoder?....................................................................................7
Is it possible to push to a Wowza server?...............................................................................................7
Filter install/Uninstall.................................................................................................................................8
installing the package automatically from the command line..................................................................8
uninstalling the package automatically from the command line..............................................................8
installing the package manually...............................................................................................................8
uninstalling the package manually...........................................................................................................8
Filter configuration.....................................................................................................................................9
Adding the filter to the graph....................................................................................................................9
Command line syntax............................................................................................................................10
Frame rate..............................................................................................................................................10
Using the built-in RTSP server................................................................................................................11
Configuring the RTSP server.................................................................................................................11
Example of 2 sources streamed on the same RTSP server..................................................................12
Example of 2 sources streamed on 2 different RTSP servers...............................................................12
Filter GUID and interface.........................................................................................................................13
Filter CLSID............................................................................................................................................13
IDatasteadMultipurposeDirectShowEncoder interface..........................................................................13
SetCommandLine..............................................................................................................................13
GetCommandLine..............................................................................................................................14
1

Stop_PauseWhenStop......................................................................................................................14
GetCurrentLog...................................................................................................................................14
IsCurrentLogUpdated........................................................................................................................15
GetExitCode.......................................................................................................................................15
GetInputsTotalDurationMs.................................................................................................................15
GetProgress_FrameCount.................................................................................................................15
GetProgress_TimeMs........................................................................................................................15
GetProgress_DuplicatedCount..........................................................................................................15
GetProgress_DroppedCount.............................................................................................................15
GetProgress_Fps...............................................................................................................................15
GetProgress_Quality.........................................................................................................................15
GetProgress_SizeWrittenKb..............................................................................................................15
GetProgress_BitRateKbps.................................................................................................................15
GetConnectedVideoPinInfo...............................................................................................................15
GetConnectedAudioPinInfo...............................................................................................................16
SetMediaEventSinkNotifyID..............................................................................................................16
Is64BitWindows.................................................................................................................................16
Is64BitApplication..............................................................................................................................16
Reserved command-line keywords........................................................................................................17
PAUSEWHENSTOP..............................................................................................................................17
SHOWCONSOLE..................................................................................................................................17
NOLOG..................................................................................................................................................17
LOWLATENCY.......................................................................................................................................17
NOABORTONERROR...........................................................................................................................17
DONTOVERWRITE...............................................................................................................................17
TOPDOWN.............................................................................................................................................18
COMPRESS...........................................................................................................................................18
RTSPPORT............................................................................................................................................18
UDPPORT..............................................................................................................................................18
RTSPSESSION......................................................................................................................................18
Graph event notification through IMediaEventEx................................................................................19
IMediaEventEx events...........................................................................................................................19
Retrieving the sender instance when several instances of the Multipurpose Encoder are used in the
same graph............................................................................................................................................19
Quick start from GraphEdit.exe..............................................................................................................21
How to debug............................................................................................................................................22
Using the filter for a normal processing, without DirectShow input..................................................23
Screenshots..............................................................................................................................................24
graphedit:...............................................................................................................................................24
graphedit with debug console:...............................................................................................................25

Overview
Features
The Datastead Multipurpose Encoder is a DirectShow Multiplexer/Sink filter able to compress or encode
audio/video streams by invoking in the background a command-line transcoder executable, if this
executable supports a named pipe as input.
A LGPL build of FFmpeg named ffmpegLGPL.exe is included in the filter.
The filter multiplexes the uncompressed DirectShow video and audio streams into an ASF transport
stream and writes this stream to a named pipe. The named pipe is taken as input by the transcoder, that
is invoked as a child process in a non-visible background process from the command line.
There is no binding or C++ linking between the filter and the transcoder, all the settings are passed by
the command-line, and the audio/video stream is passed through the named pipe.
To configure the filter, just invoke SetCommandLine and specify the desired command line, along with
some reserved keywords for the filter control.
When the graph runs, the transcoder process starts in the background, and stops when the graph is
stopped.
Additionally to this default DirectShow behavior, the "PAUSEWHENSTOP" feature allows to pause the
process while the graph is stopped, and to resume it when the graph is ran again, allowing to build in
real time a single audio/video clip from start/stop sequences separated in time.
It is possible to make the transcoder console visible for debugging or control purpose.

System requirements
Windows 7, Windows 8, Windows 8.1, Windows 10 (tested with Windows 10 preview)
32bit or 64 bit operating system supported.

Download
The evaluation package can be downloaded here:
http://www.datastead.com/products/dsfilters/multipurpose.html

License
The license agreement can be found here:
http://www.datastead.com/index.php?option=com_content&id=56
To buy a license visit our online store here:
http://www.datastead.com/purchase.html

Contact
Email:
[email protected]
[email protected].
[email protected]
Alternative email address:
[email protected]
Web:
http://www.datastead.com/contact.html

Limitations of the evaluation version

The filter overlays a "Datastead" logo over the video frames or shows a green flash one time then two
times alternatively and periodically.
These limitations are removed in the licensed version.

FAQ

Licensing
Should I buy one license for each one of my customers?
No, it's a per-developer, royalty-free license. After purchasing the developer license you can distribute
the filter along with the end-user application you have developed on as many PCs as needed, without
having to pay anything else.
Does the Multipurpose DirectShow encoder include GPL code?
No, the Multipurpose DirectShow encoder includes only a LGPL build of ffmpeg.exe. There is no GPL
code installed by the package.

Evaluation version
What are the limitations of the evaluation version?
The filter overlays a "Datastead" logo over the video frames or shows a green flash one time then two
times alternatively and periodically.
These limitations are removed in the licensed version.

Troubleshooting
GraphEdit.exe crashes when I click on "DirectShow filters" to insert a filter
The problem is an incompatibility between GraphEdit and new generation of codecs like the LAV filters
codecs.
As the LAV filters may they may required for decoding, instead of GraphEdit, use GraphStudioNext, it
has the same features and there is no compatibility problem.
The MP4 clip recorded does not play in the Windows Media Player
Verify if "-movflags frag_keyframe+empty_moov" if specified in the command-line, if yes just remove
them.
The advantage of these attributes is that they allow to create a clip that can be played while it is being
recorded. The problem being that this format is not supported by the Windows Media Player.

The frame rate is too slow

. with FFmpeg, specify the input frame rate before the input, e.g. "... -r 30 -i %PIPE%...", this could fix
the problem.
. check the codec's settings options, and choose a faster compression setting, and/or reduce the output
video size (if the time to compress 2 frames becomes longer than the time between 2 frames, frames
are dropped)
The transcoder does not not recognize the pipe input stream
Verify in the syntax help of the transcoder if you can specify additionally the pipe input format (asf). If this
does not help retry after specifying the COMPRESS keyword, however this will increase the CPU load.
When I run the graph I get a "The graph could not change state error"
The origin of the problem is usually a wrong FFmpeg command line parameter.
If you are using FFmpeg add " -report" to the command line, so you will get the FFmpeg log file in the
current folder.
The output frame rate is not stable
Specify an input frame rate.
When I run the graph it just hangs
. Usually the problem is wrong transcoder parameter syntax, a missing space, etc.... The filter verifies if
the transcoder process starts, but it does not check the syntax itself.
- if you are using FFmpeg, remove the"DONTOVERWRITE" keyword if you have added it.
If specified and the file exists, FFmpeg waits indefinitely for the manual confirmation to overwrite the file.
Using DONTOVERWRITE is not recommended for this reason.
- if FFmpeg is connecting to a remote URL (e.g. when pushing the FFmpeg output to a Wowza server),
this can takes a few seconds, and even wait until the FFmpeg connection timeout if the remote URL
does not respond.

Are transcoders others than FFmpeg supported?

The A/V stream is passed in ASF format and all the parameters can be set from the command-line, so if
the transcoder accepts a named pipe as input this should work. It may be necessary to specify
additionally some ASF demux setting for the input stream.
On the licensing aspect, take in account that many open source transcoders are under GPL license.

Does VLC work with the Multipurpose Encoder?

On the licensing aspect, same remark as above. Read the "license and proprietary application" chapter
about VideoLan on this page.
Technically, we have tested successfully some command-lines, e.g.:
MPEConfig.SetCommandLine (vlc.exe --demux ffmpeg --live-caching 20000 -vvv
stream://\\%PIPE%");
MPEConfig.SetCommandLine ("c:\\vlcfolder\\vlc.exe" --demux ffmpeg --live-caching
20000 -vvv stream://\\%PIPE%");
MPEConfig.SetCommandLine (vlc.exe --intf rc --rc-quiet --demux ffmpeg --live-caching
20000 --input-slave -v stream://\\%PIPE% --sout=\"#transcode{vcodec=xvid, vb=1500,
acodec=mpga, fps=30/1, ab=256,channels=2, samplerate=44100}:std{access=file,
mux=avi, dst=test.avi}\");

The console can be made visible with "--intf rc",

The console and player can be hidden with "--intf rc --rc-quiet".
When PAUSEWHENSTOP is enabled, we have noticed choppy audio problems when recording
audio+video with VLC.

Is it possible to push to a Wowza server?

Technically this is possible after installing a GPL version of ffmpeg.exe (the LGPL version included with
the filter does not support libx264, which is under GPL license).
The sample code is:
MPEConfig.SetCommandLine (c:\ffmpeg\ffmpeg.exe -r 30 -i %PIPE% -strict experimental
-acodec aac -ab 64k -ac 2 -vcodec libx264 -g 90 -b:v 768k -f flv rtmp://[wowzaaddress]:1935/live?doPublish=12345/streamname");

Filter install/Uninstall
The single .exe installer included in the package installs and registers automatically:
- the x86 version of the filter on Windows 32bit,
- both the x86 and x64 versions of the filter on Windows 64bit.

installing the package automatically from the command line

The command line to run the installer is:
Datastead_MultipurposeEncoder.exe /silent
or
Datastead_MultipurposeEncoder.exe /verysilent

uninstalling the package automatically from the command line

The command line to run the uninstaller is:
"C:\Program Files\Datastead\MultipurposeEncoder\unins000.exe"

installing the package manually

Double-click on the .exe installer, and accept each confirmation dialog.

uninstalling the package manually

Control panel Add/Remove program uninstall the Datastead Multipurpose DirectShow Encoder

Filter configuration
Adding the filter to the graph
1. create the filter instance
2. add the filter to the graph
3. query the filter's IDatasteadMultipurposeDirectShowEncoder interface
4. invoke SetCommandLine on this interface.
5. render the pins
6. run the graph.
E.g.:
... create filter graph...
... add video and/or audio capture devices ...
IBaseFilter *DatasteadMPE = NULL;
HRESULT hr = CoCreateInstance(CLSID_DatasteadMultipurposeDirectShowEncoder, NULL,
CLSCTX_INPROC_SERVER, (void**) &DatasteadMPE);
if (SUCCEEDED (hr)) {
hr = pGraph->AddFilter(DatasteadMPE, "Datastead Multipurpose Encoder");
if (SUCCEEDED (hr) {
IDatasteadMultipurposeDirectShowEncoder *MPEConfig;
hr = Filter.QueryInterface (IID_IDatasteadMultipurposeDirectShowEncoder,
(void**) &MPEConfig);
if (SUCCEEDED (hr) {
hr = MPEConfig.SetCommandLine (...transcoder's ".exe" command line...);
if (SUCCEEDED (hr)) {
... from render the video and audio output pins, and run the graph
}
MPEConfig->Release();
}
}
DatasteadMPE->Release();
}

Command line syntax

Example of a typical command line syntax for video recording only (e.g. for FFmpeg "-an" means "no
audio"):
MPEConfig.SetCommandLine ("ffmpegLGPL.exe -r30 -i %PIPE% -an -vcodec mpeg4 -b:v 800k
-movflags frag_keyframe+empty_moov -f mp4 outputclip.mp4");

ffmpegLGPL.exe is the name of the LGPL build of FFmpeg included in the installation folder of the filter.
Simply specify ffmpegLGPL.exe "as is" without path, it is located in the filter's folder and found
automatically without having to specify the path.
%PIPE% is mandatory for the transcoder to take the filter's output as input. I must be written
exactly as is. It corresponds to the pipe generated by the filter and used as input by the transcoder. At
runtime, %PIPE% is replaced by the real name of the pipe, generated automatically by the filter.
To use another transcoder, specify its path. This path must be specified between quotes if it contains
spaces, like in the example below, unless the transcoder can be found through the DOS search paths.
E.g. to use a third-party ffmpeg.exe that has been saved into "c:\FFmpeg folder":
MPEConfig.SetCommandLine (\"c:\\ffmpeg folder\\ffmpeg.exe\" -r 30 -i %PIPE% -strict
experimental -acodec aac -ab 128k -ac 2 -threads 6 -vcodec mpeg4 -b:v 16200k -g 30
-trellis 2 -cmp 2 -subcmp 2 -mbd rd -flags +mv4+aic \"outputclip.mp4\"");

Frame rate
Depending on the capture device, if the output frame rate looks inconsistent, specify an input frame rate.
E.g. with FFmpeg for a 30 fps input frame rate:
MPEConfig.SetCommandLine ("ffmpegLGPL.exe -r 30 -i %PIPE% ...

10

Using the built-in RTSP server

Configuring the RTSP server
The filter includes a built-in RTSP server.
To use it, 3 elements per DirectShow graph must be configured:
- the RTSP port of the RTSP server (RTSPPORT keyword),
- a session name per DirectShow graph (RTSPSESSION keyword),
- a reserved INTERNAL port per DirectShow graph (UDPPORT keyword, used only by the filter on the
127.0.0.1 internal loopback)
The port numbers can be choosen among free ports in the 554..65535 range.
The RTSP port and session name will be used to connect to the URL. E.g. if RTSPPORT=12800 and
RTSPSESSION=camera1, the clients will connect to the server with the following URL:
rtsp://ipadress:12800/camera1
The reserved port is used internally to pass the FFmpeg stream to the RTSP server through the
127.0.0.1 loopback IP address. Just write 127.0.0.1 as is, just specify the unique internal UDP port of
your choice.
Look at the examples below. Feel free to contact our support at [email protected] if something
looks confusing.
Note that if you are using several DirectShow graphs within the same applications, each couple
RTSPSESSION and UDPPORT must be unique per DirectShow graph, it must not be reused in another
DirectShow graph at the same time, as this couple represents a given DirectShow source.
E.g. of a typical RTSP server command line:
MPEConfig.SetCommandLine (SHOWCONSOLE RTSPPORT=12800 UDPPORT=12801
RTSPSESSION=camera1 ffmpegLGPL.exe -re -fflags nobuffer -flags low_delay -r 30
-vsync 1 -i %PIPE% -vcodec mpeg4 -b:v 1000k -minrate 1000k -acodec aac -ab 128k -ac
2 -strict experimental -f mpegts udp://127.0.0.1:12801?pkt_size=188&buffer_size=2048

On the client side, the connection URL will be:

rtsp://server ipadress:12800/ camera1
Note that the UDP port is passed to FFmpeg at the end of the line. The value passed to FFmpeg must
correspond to the value passed to UDPPPORT.

11

Example of 2 sources streamed on the same RTSP server

one RTSP server listening on port 20000, 2 cameras:
MPEConfig1.SetCommandLine (SHOWCONSOLE RTSPPORT=12800 UDPPORT=12801
RTSPSESSION=camera1 ffmpegLGPL.exe -re -fflags nobuffer -flags low_delay -r 30
-vsync 1 -i %PIPE% -vcodec mpeg4 -b:v 1000k -minrate 1000k -acodec aac -ab 128k -ac
2 -strict experimental -f mpegts udp://127.0.0.1:12801?pkt_size=188&buffer_size=2048
MPEConfig1.SetCommandLine (SHOWCONSOLE RTSPPORT=12800 UDPPORT=12802
RTSPSESSION=camera2 ffmpegLGPL.exe -re -fflags nobuffer -flags low_delay -r 30
-vsync 1 -i %PIPE% -vcodec mpeg4 -b:v 1000k -minrate 1000k -acodec aac -ab 128k -ac
2 -strict experimental -f mpegts udp://127.0.0.1:12802?pkt_size=188&buffer_size=2048

In this case the clients can connect with these URLs:

rtsp://server ipadress:12800/camera1
rtsp://server ipadress:12800/camera2

Example of 2 sources streamed on 2 different RTSP servers

- first RTSP server listening on port 20000, 1 camera
- 2nd RTSP server listening on port 20001, 1 camera
MPEConfig1.SetCommandLine (SHOWCONSOLE RTSPPORT=20000 UDPPORT=12801
RTSPSESSION=camera1 ffmpegLGPL.exe -re -fflags nobuffer -flags low_delay -r 30
-vsync 1 -i %PIPE% -vcodec mpeg4 -b:v 1000k -minrate 1000k -acodec aac -ab 128k -ac
2 -strict experimental -f mpegts udp://127.0.0.1:12801?pkt_size=188&buffer_size=2048
MPEConfig1.SetCommandLine (SHOWCONSOLE RTSPPORT=20001 UDPPORT=12802
RTSPSESSION=camera2 ffmpegLGPL.exe -re -fflags nobuffer -flags low_delay -r 30
-vsync 1 -i %PIPE% -vcodec mpeg4 -b:v 1000k -minrate 1000k -acodec aac -ab 128k -ac
2 -strict experimental -f mpegts udp://127.0.0.1:12802?pkt_size=188&buffer_size=2048

In this case the clients can connect with these URLs:

rtsp://ipadress:20000/camera1
rtsp://ipadress:20001/camera2

12

Filter GUID and interface

Filter CLSID
CLSID_DatasteadMultipurposeDirectShowEncoder:
TGUID = '{39E3007B-6185-47FC-9839-C4B8621AC065}';

IDatasteadMultipurposeDirectShowEncoder interface
The filter exposes the following interface:
DECLARE_INTERFACE_(IDatasteadMultipurposeDirectShowEncoder, IUnknown)
{
virtual HRESULT
STDMETHODCALLTYPE SetCommandLine(/*in*/ LPWSTR CommandLine) PURE;
virtual HRESULT
STDMETHODCALLTYPE GetCommandLine(/*out*/ LPWSTR *CommandLine) PURE;
virtual HRESULT
STDMETHODCALLTYPE Stop_PauseWhenStop() PURE;
virtual HRESULT
STDMETHODCALLTYPE GetCurrentLog(
/*in*/ bool OnlyIfUpdated,
/*in*/ PCHAR pBuffer,
/*in*/ int MaxBufferSize,
/*out*/ int *CurrentLogSize,
/*out*/ int *CurrentLogFlag) PURE;
virtual HRESULT
STDMETHODCALLTYPE IsCurrentLogUpdated() PURE;
virtual int
STDMETHODCALLTYPE GetExitCode() PURE;
virtual unsigned int STDMETHODCALLTYPE GetInputsTotalDurationMs() PURE;
virtual unsigned int STDMETHODCALLTYPE GetProgress_FrameCount() PURE;
virtual unsigned int STDMETHODCALLTYPE GetProgress_TimeMs() PURE;
virtual unsigned int STDMETHODCALLTYPE GetProgress_DuplicatedCount() PURE;
virtual unsigned int STDMETHODCALLTYPE GetProgress_DroppedCount() PURE;
virtual double
STDMETHODCALLTYPE GetProgress_Fps() PURE;
virtual double
STDMETHODCALLTYPE GetProgress_Quality() PURE;
virtual double
STDMETHODCALLTYPE GetProgress_SizeWrittenKb() PURE;
virtual double
STDMETHODCALLTYPE GetProgress_BitRateKbps() PURE;
virtual HRESULT
STDMETHODCALLTYPE GetConnectedVideoPinInfo(
/*out*/ int *VideoWidth,
/*out*/ int *VideoHeight,
/*out*/ int *VideoAvgTimePerFrame) PURE;
virtual HRESULT
STDMETHODCALLTYPE GetConnectedAudioPinInfo(
/*out*/ int *AudioChannels,
/*out*/ int *AudioSampleRate,
/*out*/ int *AudioBitsPerSample) PURE;
virtual HRESULT
STDMETHODCALLTYPE SetMediaEventSinkNotifyID (LONG_PTR Value) PURE;
virtual BOOL
STDMETHODCALLTYPE Is64BitWindows() PURE;
virtual BOOL
STDMETHODCALLTYPE Is64BitApplication() PURE;
};

SetCommandLine
Sets the FFmpeg command line, with eventual extra keywords destined to the filter. The syntax is
described here.
13

GetCommandLine
Retrieves the current command line. Pass LPWSTR pointer to the function. The function allocates
memory and copy the string. If the function succeeds, the LPWSTR pointer must be freed by invoking
CoTaskMemFree.
E.g.:
LPWSTR pCommandLine;
if (SUCCEEDED (MPEConfig.GetCommandLine (&pCommandLine))) {
... do what you need with the pCommandLine string returned
CoTaskMemFree (pCommandLine);
}

Stop_PauseWhenStop
See the PAUSEWHENSTOP keyword in the reserved keywords chapter.

GetCurrentLog
Copies the current FFmpeg log string in a buffer. If the string contains several lines, they are separated
by CR/LF characters: char(13)/char(10).
Note that this function does not work if SHOWCONSOLE has been specified.
You must allocate the buffer and pass its pointer to the function.
To determine the required maximum buffer size and allocate the buffer, invoke GetGurrentLog with all
parameters to 0 / NULL excepted CurrentLogSize that will return the size required to allocate the buffer,
e.g.:
int MaxBufferSize;
CHAR *pBuffer = NULL;
...
if (pBuffer == NULL) {
if SUCCEEDED (MPEConfig.GetCurrentLog (false, NULL, 0, &MaxBufferSize, NULL)) {
pBuffer = new CHAR[MaxBufferSize];
}
}
Then to read the current log:
int BufferSizeRead = 0;
if SUCCEEDED (MPEConfig.GetCurrentLog (true, pBuffer, BufferSize, &BufferSizeRead, NULL)) {
... do anything with the string in the buffer...
}
Notes:
OnlyIfUpdated parameter:
. if false, the buffer returns its content, even if this content has already been returned by the function
- if true and the buffer content has changed, the function fills the buffer and returns S_OK, otherwise it
returns E_NOT_SET
the buffer is "string safe": GetCurrentLog writes a NULL character at the end of the text read.

14

IsCurrentLogUpdated
return S_OK if the buffer content has changed or E_NOT_SET. It is useless to invoke it to determine if
GetBufferLog must be invoked just after, in this case invoke directly with the OnlyIfUpdated parameter =
true, e.g. GetBufferLog (true, ...) so it will return directly E_NOT_SET if no new log is available.

GetExitCode
returns the exit code, 0 on success or another value if the encoding failed for any reason (usually a
wrong command line syntax or a non-writeable output file).

GetInputsTotalDurationMs
(*)
when the input file has a fixed size, it returns the duration reported by FFmpeg in milliseconds. If several
input files are used (e.g. when concatening clips, the value returned is the total duration of final clip (the
sum of the durations of the concatened clips).

GetProgress_FrameCount
returns the current frame count (*)

GetProgress_TimeMs
returns the current stream time in milliseconds (*)

GetProgress_DuplicatedCount
returns the number of duplicated frames, if any (*)

GetProgress_DroppedCount
returns the number of dropped frames, if any (*)

GetProgress_Fps
returns the average number of frames per second (*)

GetProgress_Quality
returns the average quality (the meaning depends on the codec) (*)

GetProgress_SizeWrittenKb
return the size written to disk in KiloBytes (*)

GetProgress_BitRateKbps
returns the average bit rate in KiloBytes per second (*)
(*) these functions are currently supported only with FFmpeg, and only if SHOWCONSOLE has not been
specified.

GetConnectedVideoPinInfo
returns the video size of the input pin, and average time per frame of the video input stream (expressed
in 100 nanoseconds units, 1 second = 10000000, e.g. at 25 fps the average time per frame returns
400000)
15

GetConnectedAudioPinInfo
return the number of audio channels, the sample rate and the number of bits per sample of the audio
input pin

SetMediaEventSinkNotifyID
This is useful only:
- when processing the event notifications sent by the filter to the graph (when implementing
IMediaEventSink),
- and when using more than one instance of the Multipurpose Encoder in the same graph

Is64BitWindows
This helper function lets you know if your app is running on a Windows 64bit PC, or on a Windows 32bit
PC.

Is64BitApplication
This helper function lets you know if the application compiled in 32bit or 64bit.

16

Reserved command-line keywords

The following keywords can be specified before the command line. They are interpreted by the filter and
removed from the final command line passed to FFmpeg. E.g.:
MPEConfig.SetCommandLine (SHOWCONSOLE NOLOG ffmpegLGPL.exe -r 30 -i %PIPE%
myclip.webm");

PAUSEWHENSTOP
If specified, when the graph is stopped, the FFmpeg recording is paused (instead of being stopped as
well). When the graph is ran again, the FFmpeg recording is resumed. So this lets record a single,
continuous clip without gap, although the graph has been stopped and restarted, whatever the interval of
time between the stops and starts.
Note that when this feature is enabled, and you want to FINALLY stop the FFmpeg recording, invoke
MPEConfig.Stop_PauseWhenStop().
If Stop_PauseWhenStop is never invoked, the recorded clip will be closed when exiting the application.
Notes:
- while the graph is stopped, the video and audio pins must not be disconnected / reconnected.

SHOWCONSOLE
makes the console visible. Mainly for debugging purpose. In this mode the FFmpeg information (e.g.
current time, frame count) is not available through the the filter interface (see the interface below)

NOLOG
Can be specified to save CPU. if specified, the filter does not analyze the FFmpeg progress information
(e.g. current time, frame count), so the filter does not report them.

LOWLATENCY
Specify it if the filter is used for a live streaming in real time (e.g. to send the stream to a Wowza server).

NOABORTONERROR
If there is an error (e.g. if the syntax is not correct and/or if FFmpeg exits by itself with an error code), the
filter sends an EC_ERRORABORT notification to the graph, that stops the graph.
If
NOABORTONERROR
is
specified,
the
filter
sends
instead
an
"neutral"
EC_MPE_TERMINATED_ERROR notification to the graph that can be handled, but the graph does not
stop.

DONTOVERWRITE
by default, if the command line contains "FFmpeg", the filter passes the "-y" option to FFmpeg to
overwrite a previous clip, if any.
Set this option to prevent overwriting an existing file, however it is NOT RECOMMENDED to use it,
because if SHOWCONSOLE is disabled and FFmpeg waits for the overwrite confirmation, the graph will
17

just hang.

TOPDOWN
If specified, the image is flipped vertically without extra CPU load. Can be required by some encoders if
the image appears inverted.

COMPRESS
If specified, the video stream passed through the pipe, compressed in MPEG-4. If the command line
transcoder does not accept the pipe uncompressed, enabling this option could fix the problem.
Note that enabling this option will significantly increase the CPU load.

RTSPPORT
See the Using the built-in RTSP server chapter.

UDPPORT
See the Using the built-in RTSP server chapter.

RTSPSESSION
See the Using the built-in RTSP server chapter.

18

Graph event notification through IMediaEventEx

IMediaEventEx events
(see https://msdn.microsoft.com/en-us/library/windows/desktop/dd377538%28v=vs.85%29.aspx)
#define EC_MPE_TERMINATED_SUCCESS EC_USER + 0x5501
#define EC_MPE_TERMINATED_ERROR
EC_USER + 0x5502
#define EC_MPE_LOGBUFFER_UPDATED EC_USER + 0x5503
EC_MPE_TERMINATED_ERROR vs EC_ERRORABORT
By default, if an error occurs after the graph is ran, the filter notifies the graph with an
EC_ERRORABORT event that stops the graph.
You can prevent the filter to stop the graph by specifying the NOABORTONERROR keyword at the
beginning of the command line. In this case, if an error occurs the filter sends a
EC_MPE_TERMINATED_ERROR notification message that you can handle but that does not stop the
graph.
EC_MPE_TERMINATED_SUCCESS
If the FFmpeg processing ends successfully before the graph is stopped (e.g. if a maximal encoding
duration
has
been
specified
to
the
command
line),
the
filter
sends
a
EC_MPE_TERMINATED_SUCCESS event to the graph.
EC_MPE_LOGBUFFER_UPDATED
Each time the log buffer has been updated, the filter sends a EC_MPE_LOGBUFFER_UPDATED event
to the graph.
When this event is received you can successfully invoke GetCurrentLog to retrieve the log content, or
read one of the GetProgress... functions to retrieve the corresponding value.

Retrieving the sender instance when several instances of the Multipurpose

Encoder are used in the same graph
For all the events described above, Param1 and Param2 return the following values:
Param1:
returns the exit code of FFmpeg
Param2:
- by default Param2 returns the pointer to the instance of the filter (the same IBaseFilter pointer that has
been returned when you invoked
CoCreateInstance(CLSID_DatasteadMultipurposeDirectShowEncoder...)
- when configuring the filter, if you have invoked SetMediaEventSinkNotifyID (Value) with a value of your
19

choice, Param2 returns this value (instead of the IBaseFilter pointer)

In the case where several Multipurpose Encoders are used within the same graph, any of these 2
mechanisms lets you easily retrieve what instance of the Multipurpose Encoder sent the event
notification.

20

Quick start from GraphEdit.exe

- run GraphEdit -> Graph -> Insert Filters -> DirectShow Filters
- locate the "Datastead Multipurpose Encoder" filter, double-click on it to insert it,
- insert the video source filter (e.g. a Webcam) and/or the audio source filter (e.g. a microphone)
- connect video output pin (if any) to the Multipurpose video input pin
- connect audio output pin (if any) to the Multipurpose audio input pin
- right-click on the "Datastead Multipurpose Encoder" filter, and enter the command line, eventually
preceded by reserved Multipurpose keywords.
Examples of a very minimalistic command line that can be tested "out the box":
- with console, for debugging purpose:
SHOWCONSOLE ffmpegLGPL.exe -r 30 -i %PIPE% myclip.webm
- or not visible, like a normal DirectShow sink filter:
ffmpegLGPL.exe -r 30 -i %PIPE% myclip.webm

21

How to debug
First verify if the solution is not in the the Support section of the FAQ. If not:
1. add "SHOWCONSOLE" at the beginning of the command line, to see if the FFmpeg process starts
and if any red error report appears.
2. add " -report" or " -report -loglevel debug" to the command line, this will generate the FFmpeg log file
in the current folder.
Verify/fix the FFmpeg syntax, then try again.
PS: don't forget to remove the report and loglevel statements because they slow-down the filter.

22

Using the filter for a normal processing, without DirectShow

input.
To avoid having to implement specific code for editing or transcoding that do not use the pipe as input,
you can use the filter for a normal batch transcoding as follows:
- add the filter to the graph (alone without connecting any pin)
- configure command line with a normal command line (without "%PIPE%")
- run the graph
The progress log and completion notification events work the same way.
E.g.:

23

Screenshots
graphedit:

24

graphedit with debug console:

25