Please enable JavaScript to view this site.

KOL/MCK - User Guide

TMediaPlayer = object( TObj )

MediaPlayer encapsulation object. Can open and play any supported by system multimedia file. (To play wave only, it is possible to use functions PlaySound..., which can also play it from memory and from resource).

Please note, that while debugging, You can get application exception therefore standalone application is working fine. (Such results took place for huge video).

 

type PMediaPlayer = ^TMediaPlayer;

 

type TMPState = ( mpNotReady, mpStopped, mpPlaying, mpRecording, mpSeeking, mpPaused, mpOpen );

Available states of TMediaPlayer.

 

type TMPDeviceType = ( mmAutoSelect, mmVCR, mmVideodisc, mmOverlay, mmCDAudio, mmDAT, mmScanner, mmAVIVideo, mmDigitalVideo, mmOther, mmWaveAudio, mmSequencer );

Available device types of TMediaPlayer.

 

type TMPTimeFormat = ( tfMilliseconds, tfHMS, tfMSF, tfFrames, tfSMPTE24, tfSMPTE25, tfSMPTE30, tfSMPTE30Drop, tfBytes, tfSamples, tfTMSF );

Available time formats, used with properties Length and Position.

 

type TMPNotifyValue = (nvSuccessful, nvSuperseded, nvAborted, nvFailure);

Available notification flags, which can be passed to TMediaPlayer.OnNotify event handler (if it is set).

 

type TMPOnNotify = procedure( Sender: PMediaPlayer; NotifyValue: TMPNotifyValue ) of object;

Event type for TMediaPlayer.OnNotify event.

 

type TPlayOption = ( poLoop, poWait, poNoStopAnotherSound, poNotImportant );

Options to play sound. poLoop, when sound is playing back repeatedly until PlaySoundStop called. poWait, if sound is playing synchronously (i.e. control returns to application after the sound event completed). poNoStopAnotherSound means that another sound playing can not be stopped to free resources needed to play requested sound. poNotImportant means that if driver busy, function will return immediately returning False (with no sound playing).

 

type TPlayOptions = set of TPlayOption;

Options, available to play sound from memory or resource or to play standard sound event using PlaySoundMemory, PlaySoundResourceID, PlaySoundResourceName, PlaySoundEvent.

 

type TSoundChannel = ( chLeft, chRight );

Available sound channels.

 

type TSoundChannels = set of TSoundChannel;

Set of available sound channels.

 

 

TMediaPlayer Properties

 

property FileName: String;

Name of file, containing multimedia, if any (some multimedia devices do not require file, corresponding to device rather then file. Such as mmCDAudio, mmScanner, etc. Use in that case DeviceType property to assign to desired type of multimedia and then open it using Open method).

When new string is assigned to a FileName, previous media is closed and another one is opened automatically.

 

property DeviceType: TMPDeviceType;

Type of multimedia. For opened media, real type is returned. If no multimedia (device or file) opened, it is possible to set DeviceType to desired type before opening multimedia. Use such way for opening devices rather then for opening multimedia, stored in files.

 

property DeviceID: Integer;

Returns DeviceID, corresponded to opened multimedia (0 is returned if no media opened.

 

property TimeFormat: TMPTimeFormat;

Time format, used to set/retrieve information about Length or Position. Please note, that not all formats are supported by all multimedia devices.

Only tfMilliseconds (is set by default) supported by all devices. Following table shows what devices are supporting certain time formats:

 

tfMilliseconds

All multimedia device types

tfBytes

mmWaveAudio

tfFrames

mmDigitalVideo

tfHMS

(hours, minutes, seconds)> mmVCR (video cassete recorder), mmVideodisc.

It is necessary to parse retrieved Length or Position or to prepare value before assigning it to Position using typecast to THMS.

tfMSF

(minutes, seconds, frames)> mmCDAudio, mmVCR. It is necessary to parse value retrieved from Length or Position properties or value to assign to property Position using typecast to TMSF type.

tfSamples

mmWaveAudio

tfSMPTE24, tfSMPTE25, tfSMPTE30, tfSMPTE30DROP (Society of Motion Picture and Television Engineers)

mmVCR, mmSequencer

tfTMSF

(tracks, minutes, seconds, frames) mmVCR

 

property Position: Integer;

Current position in milliseconds. Even if device contains several tracks, this is the position from starting of first track. To determine position in current Track, subtract TrackStartPosition.

 

 

property Track: Integer;

Current track (from 1 to TrackCount). Has no sence, if tracks are not supported by opened multimedia device, or no tracks present.  

 

property TrackCount: Integer;

Count of tracks for opened multimedia device. If device does not support tracks, or tracks not present (e.g. there are no tracks found on CD), value 1 is returned by system (but this not a rule to determine if tracks are available).

 

property Length: Integer;

Length of multimedia in milliseconds. Even if device has tracks, this the length of entire multimedia.

 

property Display: HWnd;

Window to represent animation. It is recommended to create neutral control (e.g. label, or paint box, and assign its TControl.Handle to this property). Has no sense for multimedia, which HasVideo = False (no animation presented).

 

property DisplayRect: TRect;

Rectangle in Display window, where animation is shown while playing animation. To restore default value, pass Bottom = Top = 0 and Right = Left = 0.

 

property Error: Integer;

Error code. Is set after every operation. If 0, no errors detected. It is also possible to retrieve description string for error using property ErrorMessage.

 

property ErrorMessage: String;

Brief description of Error.

 

property State: TMPState;

Current state of multimedia.

 

property Pause: Boolean;

True, if multimedia currently not playing (or not open). Set this property to True to pause playing, and to False to resume.

 

property Wait: Boolean;

True, if operations will be performed synchronously (i.e. execution will be continued only after completing operation). If Wait is False (default), control is returned immediately to application, without waiting of completing of operation. It is possible in that case to get notification about finishing of previous operation in OnNotify event handler (if any has been set).

 

 

property TrackStartPosition: Integer;

Returns given track starting position (in units, specisied by TimeFormat property. E.g., if TimeFormat is set to (default) tfMilliseconds, in milliseconds).

 

property TrackLength: Integer;

Returns given track length (in units, specified by TimeFormat property).

 

 

property Width: Integer;

Default width of video display (for multimedia, having video animation).

 

property Height: Integer;

Default height of video display (for multimedia, having video animation).

 

property Alias: String;

Alias for opened device. Must be set before opening (before changing FileName).

 

property Ready: Boolean;

True if Device is ready.

 

property IsCompoundDevice: Boolean;

True, if device is compound.

 

property HasVideo: Boolean;

True, if multimedia has videoanimation.

 

property HasAudio: Boolean;

True, if multimedia contains audio.

 

property CanEject: Boolean;

True, if device supports "open door" and "close door" operations.

 

property CanPlay: Boolean;

True, if multimedia can be played (some of deviceces are only for recording, not for playing).

 

property CanRecord: Boolean;

True, if multimedia can be used to record (video or/and audio).

 

property CanSave: Boolean;

True, if multimedia device supports saving to a file.

 

property Present: Boolean;

True, if CD or videodisc inserted into device.

 

property AudioOn[ Chn: TSoundChannels ]: Boolean;

Returns True, if given audio channels (both if [chLeft,chRight], any if []) are "on". This property also allows to turn desired channels on and off.

 

property VideoOn: Boolean;

Returns True, if video is "on". Allows to turn video signal on and off.

 

 

For "CDAudio" only:

 

property CDTrackNotAudio: Boolean;

True, if current Track is not audio.

 

 

For "digitalvideo":

 

property DGV_CanFreeze: Boolean;

True, if can freeze.

 

property DGV_CanLock: Boolean;

True, if can lock.

 

property DGV_CanReverse: Boolean;

True, if can reverse playing.

 

property DGV_CanStretchInput: Boolean;

True, if can stretch input.

 

property DGV_CanStretch: Boolean;

True, if can stretch output.

 

property DGV_CanTest: Boolean;

True, if supports Test.

 

property DGV_HasStill: Boolean;

True, if has still images in video.

 

property DGV_MaxWindows: Integer;

Returns maximum windows supported.

 

property DGV_MaxRate: Integer;

Returns maximum possible rate (frames/sec).

 

property DGV_MinRate: Integer;

Returns minimum possible rate (frames/sec).

 

property DGV_Speed: Integer;

Returns speed of digital video as a ratio between the nominal frame rate and the desired frame rate where the nominal frame rate is designated as 1000. Half speed is 500 and double speed is 2000. The allowable speed range is dependent on the device and possibly the file, too.

 

 

For AVI only (mmDigitalVideo, AVI-format):

 

property AVI_AudioBreaks: Integer;

Returns the number of times that the audio definitely broke up. (We count one for every time we're about to write some audio data to the driver, and we notice that it's already played all of the data we have).

 

property AVI_FramesSkipped: Integer;

Returns number of frames not drawn during last play.  If this number is more than a small fraction of the number of frames that should have been displayed, things aren't looking good.

 

property AVI_LastPlaySpeed: Integer;

Returns a number representing how well the last AVI play worked. A result of 1000 indicates that the AVI sequence took the amount of time to play that it should have; a result of 2000, for instance, would indicate that a 5-second AVI sequence took 10 seconds to play, implying that the audio and video were badly broken up.

 

 

For  "vcr" (video cassete recorder):

 

property VCR_ClockIncrementRate: Integer;

 

property VCR_CanDetectLength: Boolean;

True, if can detect Length.

 

property VCR_CanFreeze: Boolean;

True, if supports command "freeze".

 

property VCR_CanMonitorSources: Boolean;

True, if can monitor sources.

 

property VCR_CanPreRoll: Boolean;

True, if can preroll.

 

property VCR_CanPreview: Boolean;

True, if can preview.

 

property VCR_CanReverse: Boolean;

True, if can play in reverse direction.

 

property VCR_CanTest: Boolean;

True, if can test.

 

property VCR_HasClock: Boolean;

True, if has clock.

 

property VCR_HasTimeCode: Boolean;

True, if has time code.

 

property VCR_NumberOfMarks: Integer;

Returns number of marks.

 

property VCR_SeekAccuracy: Integer;

Returns seek accuracy.

 

 

For mmWaveAudio:

 

property Wave_AvgBytesPerSecond: Integer;

Returns current bytes per second used for playing, recording, and saving.

 

property Wave_BitsPerSample: Integer;

Returns current bits per sample used for playing, recording, and saving PCM formatted data.

 

property Wave_SamplesPerSecond: Integer;

Returns current samples per second used for playing, recording, and saving.

 

 

TMediaPlayer Methods

 

function Open: Boolean;

Call this method to open device, which is not correspondent to file. For multimedia, stored in file, Open is called automatically when FileName property is changed.

Multimedia is always trying to be open shareable first. If it is not possible, second attempt is made to open multimedia without sharing.

 

function Play( StartPos, PlayLength: Integer ): Boolean;

Call this method to play multimedia. StartPos is relative to starting position of opened multimedia, even if it has tracks. If value passed for StartPos is -1, current position is used to start from.

If -1 passed as PlayLength, multimedia is playing to the end of media.

Note, that after some operation (including Play) current position is moved and it is necessary to pass 0 as StartPos to play multimedia from its starting position again. To provide playing the same multimedia several times, call:

with MyMediaPlayer do
Play( 0, -1 );

To Play single track, call:

with MyMediaPlayer do
begin
 Track := N; // set track to desired number
 Play( TrackStartPosition, TrackLength );
end;

 

procedure Close;

Closes multimedia. Later it can be reopened using Open method. Please remember, that if CDAudio (e.g.) is playing, it is not stop playing when Close is called. To stop playing, first perform command Pause := True;

 

procedure Eject;

Ejects media from device. It is possible to check first, if this operation is supported by the device - see CanEject.

 

procedure DoorClose;

Backward operation to Eject - inserts media to device. This operation is very easy and does not take in consideration if CD data / audio is playing automatically when media is inserted. To prevent launching CD player or application, defined in autostart.inf file in rootof CD, use Insert method instead.

 

procedure DisableAutoPlay;

Be careful when using this method - this affects user settings such as 'Autoplay CD audio disk' and 'Autorun CD Data disk'. At least do not forget to restore settings later, using RestoreAutoPlay method. When You use Insert method to insert CD into device, DisableAutoPlay also is called, but in that case restoring is made automatically at least when TMediaPlayer object is destroying.

 

procedure RestoreAutoPlay;

Restores settings CD autoplay settings, changed by calling DisableAutoPlay method (which must be called earlier to save settings and change it to disable CD autoplay feature). It is not necessary to call RestoreAutoPlay only in case, when method Insert was used to insert CD into device (but calling it restores settings therefore - so it is possible to restore settings not only when object TMediaPlayer destroyed, but earlier.

 

procedure Insert;

Does the same as DoorClose, but first disables auto play settings, preventing system from running application defined in Autorun.inf (in CD root) or launching CD player application. Such settings will be restored at least when TMediaPlayer object is destroyed, but it is possible to call RestoreAutoPlay earlier (but there is no sence to call it immediately after performing Insert method - at least wait several seconds or start playing track first).

 

function Save( const aFileName: String ): Boolean;

Saves multimedia to a file. Check first, if this operation is supported by device.

 

function StartRecording( FromPos, ToPos: Integer ): Boolean;

Starts recording. If FromPos is passed -1, recording is starting from current position. If ToPos is passed -1, recording is continuing up to the end of media.

 

function Stop: Boolean;

Stops playing back or recording.

 

function SendCommand( Cmd, Flags: Integer; Buffer: Pointer ): Integer;

Low level access to a device. To get know how to use it, see sources.

 

function NewMediaPlayer( const FileName: String; Window: HWND ): PMediaPlayer;

Creates TMediaPlayer instance. If FileName is not empty string, file is opening immediately.

 

function PlaySoundMemory( Memory: Pointer; Options: TPlayOptions ): Boolean;

Call it to play sound already stored in memory. (It is possible to preload sound from resource (e.g., using Resurce2Stream function) or to load sound from file.

 

function PlaySoundResourceID( Inst, ResID: Integer; Options: TPlayOptions ): Boolean;

Call it to play sound, stored in resource. It is also possible to stop playing certain sound, asynchronously playing from a resource, using PlaySoundStopResID.

In this implementation, sound is played from memory and always with poWait option turned on (i.e. synchronously).

 

function PlaySoundResourceName( Inst: Integer; const ResName: String; Options: TPlayOptions ): Boolean;

Call it to play sound, stored in (named) resource. It is also possible to stop playing certain sound, asynchronously playing from a resource, using PlaySoundStopResName.

In this implementation, sound is played from memory and always with poWait option turned on (i.e. synchronously).

 

function PlaySoundEvent( const EventName: String; Options: TPlayOptions ): Boolean;

Call it to play standard event sound. E.g., 'SystemAsterisk', 'SystemExclamation', 'SystemExit', 'SystemHand', 'SystemQuestion', 'SystemStart' sounds are defined for all Win32 implementations.

 

function PlaySoundFile( const FileName: String; Options: TPlayOptions ): Boolean;

Call it to play waveform audio file. (This also can be done using TMediaPlayer, but for wide set of audio and video formats).

 

function PlaySoundStop: Boolean;

Call it to stop playing sounds, which are yet playing (after calling PlaySountXXXXX functions above to play sounds asynchronously).

 

 

function WaveOutChannels( DevID: Integer ): TSoundChannels;

Returns available sound output channels for given wave out device. Pass -1 (or WAVE_MAPPER) to get channels for wave mapper. If only mono output available, [ chLeft ] is returned.

 

function WaveOutVolume( DevID: Integer; Chn: TSoundChannel; NewValue: Integer ): Word;

Sets volume for given channel. If NewValue = -1 passed, new value is not set. Always returns current volume level for a channel (if successful). Volume varies in diapason 0..65535. If passed value > 65535, low word of NewValue is used to set both chLeft and chRight channels.

 

 

TMediaPlayer Events

 

property OnNotify: TMPOnNotify;

Called when asynchronous operation completed. (By default property Wait is set to False, so all operations are performed asynchronously, i.e. control is returned to application without of waiting of completion operation). Please note, that system can make several notifications while performing operation. To determine if operation completed, check State property.

E.g., to find where playing is finished, check in OnNotify event handler if State <> mpPlaying.

 

Though TMediaPlayer works fine with the most of multimedia formats (at least it is tested for WAV, MID, RMI, AVI (video and sound), MP3 (soound), MPG (video and sound) ), there are some problems with getting notifications about finishing MP3 playing: when OnNotify is called, State returned is mpPlaying yet. For that case I can advice to check also playing time and compare it with Length of multimedia.

 

KOL / MCK User Guide - Created by Carl Peeraer - Diamant Soft, based on the work of Vladimir Kladov - Artwerp.be

  

Keyboard Navigation

F7 for caret browsing
Hold ALT and press letter

This Info: ALT+q
Nav Header: ALT+n
Page Header: ALT+h
Topic Header: ALT+t
Topic Body: ALT+b
Exit Menu/Up: ESC