Player features

About the player.

Description

Player features

TVideoGrabber includes an advanced player that allows to play video clips, capture video frames and perform frame overlay when the frame grabber is enabled.

It is possible to play multiple video clips seamlessly with the Seamless playback feature.

Opening / pausing / running / closing the clip

- set the PlayerFileName property with the full qualified path or the URL of the video clip,
- open the clip with OpenPlayer

When the clip is opened the OnPlayerOpened event occurs. From this event you can read the PlayerDuration and PlayerFrameCount properties, e.g. to setup a trackbar (see below the trackbar chapter)

To open a clip in a paused state:
VideoGrabber.PlayerFileName = "myclip.avi"
VideoGrabber.AutoStartPlayer = false
VideoGrabber.OpenPlayer()

To open and play a clip immediately:
VideoGrabber.PlayerFileName = "myclip.avi"
VideoGrabber.AutoStartPlayer = true
VideoGrabber.OpenPlayer()

To pause a clip during playback:
VideoGrabber.PausePlayer()

To resume the playback when the clip is paused:
VideoGrabber.RunPlayer()

To close the clip:
VideoGrabber.ClosePlayer()

Player seeking

Ater opening the video clip, you can set a new position by assigning:

- either the PlayerFramePosition property, in the 1..PlayerFrameCount range

- either the PlayerTimePosition property, in the 0..PlayerDuration range (expressed in 100ns units, e.g. 2 seconds = 20000000)

To set the current position at the frame #500:
VideoGrabber.PlayerFramePosition = 500

To specify a new position located at "15 seconds":
VideoGrabber.PlayerTimePosition = 150000000

Frame counting and frame seeking

By default the frame counting / frame seeking starts from 1 (the 1st frame is the frame #1).

Alternatively it is possible to let TVideoGrabber start from the frame #0 by enabling the FrameNumberStartsFromZero property.

Frame stepping

When the clip is paused, you can invoke PlayerFrameStep (1) to step to the next frame.

It is possible to specify a value > 1 to skip n-1 frames, e.g. PlayerFrameStep (10) will skip the next 9 frames and display the 10th frame.

Note that with MPEG video clips PlayerFramePosition and PlayerTimePosition can reach only key frames, whereas PlayerFrameStep will step through all the frames (key frames and delta frames).

Seeking
If the clip is seekable it can be played backwards using RunPlayerBackwards , however the play back is not as smooth as normal play back.
Note that you can get a more effective reverse playback by opening the clip through AVISynth, as expained in the Advanced playback through AVISynth chapter.

To scan the clip quickly:
- forwards use FastForwardPlayer ,
- backwards use RewindPlayer ,
The scan speed can be modified using PlayerFastSeekSpeedRatio .

Keeping the last video frame visible while opening the next video clip
By default after invoking ClosePlayer, the video window is closed until the next clip is opened.

Enable the VideoVisibleWhenStopped property to keep the video window active after the previous video ends.
Then the last video frame will remain displayed until OpenPlayer is invoked and the new video clip starts playing.

Playback boundaries
Instead of invoking OpenPlayer:
- invoke OpenPlayerAtFramePositions to open a clip at the specified start frame
- invoke OpenPlayerAtTimePositions to open a clip at the specified stop frame

If the KeepBound parameter is true, the clip is played within the start and stop boundaries specified.
When the clip is already opened, invoking OpenPlayerAtFramePositions or OpenPlayerAtTimePositions modifies the playback boundaries without reopening the clip.

Playback progress
During playback, information about each video frame is reported by the OnFrameProgress event.

End of stream
When the end of stream is reached the OnPlayerEndOfStream event occurs.
From this event you can invoke any task, e.g. you can invoke RunPlayer to restart the playback from the beginning.

Paused player and CPU consumption
When a video clip is paused and:
- the PlayerRefreshPausedDisplay property is enabled,
- the FrameGrabber property is enabled,
the display is refreshed periodically at a frame rate specified by PlayerRefreshPausedDisplayFrameRate, in order to get the text and graphics overlays refreshed.

However this feature requires CPU. To reduce the CPU consumption when a video clip is paused, you can:

- specify a lower PlayerRefreshPausedDisplayFrameRate value,
- disable the PlayerRefreshPausedDisplay property.

Playback speed
A clip is played at its normal speed when PlayerSpeedRatio = 1.

It is possible to play video clips at different speeds, however the playback speed range is larger if the audio rendering is disabled. To play a clip at a different speed:
- with audio rendering, enable PlayerAudioRendering and modify PlayerSpeedRatio in the 0.5 to 2.0 range,
- without audio rendering, disabled PlayerAudioRendering and modify PlayerSpeedRatio in a larger range.

Playing clips at max speed without clock
It is possible to play the clips without clock, this guarantee e.g. that all the frames will be captured in burst mode (when BurstMode = true and BurstCount = 0).
To enable this feature, disable UseClock before invoking OpenPlayer.

Player trackbar
TVideoGrabber handles automatically a player trackbar (Delphi and C++Builder versions ONLY).
Simply put a trackbar on the form, and then associate it by assigning it from the Object Inspector to the PlayerTrackBar property.
See the PlayerTrackBar and the PlayerTrackBarScale properties for more information.

Frame capture during playback
Video frames can be captured during playback. See the Frame capture chapter.

Audio playback
For video clips that has an audio stream (when IsPlayerAudioStreamAvailable returns ts_True), you can disable the rendering of the audio stream by setting PlayerAudioRendering to false. This can help to play video clips slower than 0.5 or faster than 2.

Selecting the audio sound card
You can specify the soundcard used for the playback rendering by assigning the AudioRenderer index with the index of the sound card in the AudioRenderers list.
e.g. if the index in the list is 2:
VideoGrabber.AudioRenderer = 2
OR
e.g. if the name in the list is "Speakers (Blackmagic Audio":
VideoGrabber.AudioRenderer = VideoGrabber.AudioRendererIndex ("Speakers (Blackmagic Audio")

Selecting only the right or left audio channel
It is possible to convert the right channel or the left channel as "mono" and to mute either the left, right or both channels, or to convert a mono channel into stereo with AudioChannelRenderMode.

Selecting one audio stream when the clip has multiple audio streams
When the clip has multiple audio streams it is possible to select only one audio stream with AudioStreamNumber

Codec used during playback
It is possible to force the use of a given codec by assigning a codec name or a codec GUID to PlayerForcedCodec .

The video codec and audio codec using during playback are reported by the PlayerVideoCodec and PlayerAudioCodec properties.

Specifying the buffering time when playing a streaming URL
The buffering time can be adjusted by invoking ShowDialog (dlg_NetShowConfig)

Authentication

If an authentication is required to connecto a streaming url, there are 2 ways to set an username and password required:
- either by invoking SetAuthentication (at_StreamingUrl, "...username...", "...password..." ) before invoking OpenPlayer,
- either through the OnAuthenticationNeeded event that will occur when connecting if SetAuthentication has not been invoked yet.