Skip to content

Filter GUID and interface

Filter CLSIDs

Constant GUID Filter
CLSID_DatasteadMultipurposeDirectShowEncoder {39E3007B-6185-47FC-9839-C4B8621AC065} Datastead Multipurpose Encoder: encodes the samples of the connected video and/or audio pins
CLSID_DatasteadMultipurposeDirectShowEncoderFromFile {A4EEBEBE-A375-4995-8DBC-F4E42A189D6A} Datastead Multipurpose Encoder (From File): encodes the file passed through IFileSourceFilter; no pin to connect
CLSID_DatasteadDirectShowEncoder {6E990010-F426-491B-8CBE-2CA95A70B6D5} Datastead Encoder: encodes the connected pins through codec settings instead of an FFmpeg command line; this is the filter used by the TVideoGrabber SDK

Delphi declaration:

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

The constants above, the interface declarations and the event codes are declared in the include files of the package:

Language Declaration file
C++ include\Cpp\DatasteadMultiPurposeEncoderConfig.h (and the matching .idl)
C# include\CSharp\DatasteadMultiPurposeEncoderConfig.cs
Delphi include\Delphi\DatasteadMultiPurposeEncoderConfig.pas

Interfaces

All the interfaces below are obtained with QueryInterface on the IBaseFilter of the encoder.

Interface IID Purpose
IDatasteadMultipurposeDirectShowEncoder {43F00ED1-5F85-4C7E-98AC-AD5E13111D34} main interface: command line, log, progress and pin information (below)
IDatasteadMultipurposeDirectShowEncoder2 {61654563-047A-4DA1-979C-CFA17D36F1D2} GetVersion: returns the version of the filter
IDatasteadMultipurposeDirectShowEncoderIDL {F7F2BE3A-C4AC-43DB-8582-98E925CC2FE2} automation-friendly variant of the main interface
IDatasteadMultipurposeDirectShowEncoderProcess {938A2753-65A8-4FD4-9A82-9B81BB3F889B} GetMPEProcessID: returns the process ID of the transcoder started by the filter
IDatasteadMultipurposeDirectShowEncoderControl {E334D3D6-2F67-4178-BFAF-DBFA3413053E} PauseEncoder / ResumeEncoder
IFileSourceFilter standard DirectShow exposed by the (From File) filter, to set the file to encode
ISpecifyPropertyPages standard DirectShow property pages of the filter: the encoder settings page on the Datastead Encoder filter, the command line and log pages on the two command-line filters
IPersistStream standard DirectShow saves and restores the configuration of the filter: the encoder settings on the Datastead Encoder filter, the command line on the two command-line filters

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, optionally preceded by the reserved keywords interpreted by the filter. The syntax is described in the Command-line syntax chapter.

Three forms of call do not set a command line and return immediately:

GetCommandLine

Retrieves the current command line. Pass a LPWSTR pointer to the function. The function allocates memory and copies the string. If the function succeeds, the LPWSTR pointer must be freed by invoking CoTaskMemFree.

E.g.:

LPWSTR pCommandLine;
if (SUCCEEDED (MPEConfig->GetCommandLine (&pCommandLine))) {
   // ... use 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.

The buffer is allocated by the application, which passes its pointer to the function.

To determine the required maximum buffer size and allocate the buffer, invoke GetCurrentLog 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, MaxBufferSize, &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.

IsCurrentLogUpdated

Returns S_OK if the buffer content has changed, or E_NOT_SET. It is useless to invoke it to determine if GetCurrentLog must be invoked just after: in this case invoke GetCurrentLog directly with the OnlyIfUpdated parameter = 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 concatenating clips), the value returned is the total duration of the final clip (the sum of the durations of the concatenated 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

Returns the size written to disk in kilobytes. (*)

GetProgress_BitRateKbps

Returns the average bitrate in kilobits 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).

GetConnectedAudioPinInfo

Returns the number of audio channels, the sample rate and the number of bits per sample of the audio input pin.

SetMediaEventSinkNotifyID

Sets the value returned as Param2 by the notification events. 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.

See Graph event notifications.

Is64BitWindows

Reports whether the application is running on a 64-bit or on a 32-bit version of Windows.

Is64BitApplication

Reports whether the application itself is compiled in 32-bit or in 64-bit.

Automation-friendly interface

The methods of IDatasteadMultipurposeDirectShowEncoder that return a value directly (GetExitCode, the GetProgress_... family, Is64BitWindows, Is64BitApplication) are not usable from every language. IDatasteadMultipurposeDirectShowEncoderIDL exposes the same functionality with a uniform signature: every method returns an HRESULT and gives its value back through an out parameter.

HRESULT GetExitCode                 (/*out*/ int *ExitCode);
HRESULT GetInputsTotalDurationMs    (/*out*/ unsigned int *InputsTotalDurationMs);
HRESULT GetProgress_FrameCount      (/*out*/ unsigned int *Progress_FrameCount);
HRESULT GetProgress_TimeMs          (/*out*/ unsigned int *Progress_TimeMs);
HRESULT GetProgress_DuplicatedCount (/*out*/ unsigned int *Progress_DuplicatedCount);
HRESULT GetProgress_DroppedCount    (/*out*/ unsigned int *Progress_DroppedCount);
HRESULT GetProgress_Fps             (/*out*/ double *Progress_Fps);
HRESULT GetProgress_Quality         (/*out*/ double *Progress_Quality);
HRESULT GetProgress_SizeWrittenKb   (/*out*/ double *Progress_SizeWrittenKb);
HRESULT GetProgress_BitRateKbps     (/*out*/ double *Progress_BitRateKbps);
HRESULT Is64BitWindows              (/*out*/ BOOL *Is_64BitWindows);
HRESULT Is64BitApplication          (/*out*/ BOOL *Is64_BitApplication);
HRESULT GetVersion                  (/*out*/ unsigned int *Version);

The other methods (SetCommandLine, GetCommandLine, Stop_PauseWhenStop, GetCurrentLog, IsCurrentLogUpdated, GetConnectedVideoPinInfo, GetConnectedAudioPinInfo, SetMediaEventSinkNotifyID) behave exactly as in the main interface.

Tip

This is the interface used by the C# and Delphi declarations shipped in the include folder of the package.

Pausing the encoder

IDatasteadMultipurposeDirectShowEncoderControl pauses and resumes the encoding while the graph keeps running:

HRESULT PauseEncoder ();
HRESULT ResumeEncoder ();

Unlike PAUSEWHENSTOP, which is driven by the state of the graph, these two methods are driven by the application.

Transcoder process

IDatasteadMultipurposeDirectShowEncoderProcess returns the process ID of the transcoder started by the filter, which is useful to monitor that process from the application:

HRESULT GetMPEProcessID (/*out*/ DWORD ProcessID);