IMediaSeeking::SetRate method (strmif.h)

Article
07/27/2023

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The SetRate method sets the playback rate.

Syntax

HRESULT SetRate(
  [in] double dRate
);

Parameters

[in] dRate

Playback rate. Must not be zero.

Return value

Returns an HRESULT value. Possible values include the following.

Return code	Description
S_OK	Success.
E_INVALIDARG	The specified rate was zero or a negative value. (See Remarks.)
E_NOTIMPL	Not implemented.
E_POINTER	NULL pointer argument.
VFW_E_UNSUPPORTED_AUDIO	Audio device or filter does not support this rate.

Remarks

The playback rate is expressed as a ratio of the normal speed. Thus, 1.0 is normal playback speed, 0.5 is half speed, and 2.0 is twice speed. For audio streams, changing the rate also changes the pitch.

Negative values indicate reverse playback. Most filters do not support negative playback, but instead return an error code if the dRate parameter is negative.

When an application calls this method on the Filter Graph Manager, the Filter Graph Manager does the following:

Calls the IMediaSeeking::GetCurrentPosition method. This call returns the current position as calculated by the Filter Graph Manager.
Stops the filter graph (if the graph is paused or running).
Calls the IMediaSeeking::SetPositions method on the filters, with the current position as the start time. This has the effect of resetting the stream time to zero.
Calls the SetRate method on the filters, with the new rate.
Resumes the filter graph, if it was paused or running.

If an error occurs in step 4, the Filter Graph Manager tries to restore the previous rate.

Filters should respond to rate changes as follows:

Parser and source filters: The filter that originates the timestamps responds to the SetRate call. This is usually a parser filter, such as the AVI Splitter Filter, but it might be a source filter. After any seek or rate change, the filter should call the IPin::NewSegment method with the new settings. After a rate change, it should adjust its timestamps accordingly. Because a rate change is preceded by a seek, timestamps restart from zero, so the filter can simply divide by the rate to calculate the new timestamps.

Decoder filters: Decoders should not act on SetRate calls other than to pass them upstream. Instead, they should respond to the NewSegment call that the upstream parser issues. When a decoder filter receives new segment information, it should store the values and pass the NewSegment call downstream. Some decoders need to generate extra timestamps by interpolating their input; they should take rate changes into account when doing so.

Renderers: Video renderers can typically ignore rate changes, because the incoming frames already have the correct time stamp. Audio renderers must modify their playback rate, because audio decoders typically do not make rate-change conversions.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	strmif.h (include Dshow.h)
Library	Strmiids.lib