TeamTalk 5 C-API DLL  Version 5.14A
Stream Media Files

This section explains how to stream media files to channels. More...

Classes

struct  AudioFormat
 Struct describing the audio format used by a media file. More...
 
struct  MediaFileInfo
 Struct describing the audio and video format used by a media file. More...
 
struct  MediaFilePlayback
 Properties for initializing or updating a file for media streaming. More...
 
struct  AudioInputProgress
 The progress of the audio currently being processed as audio input. More...
 

Macros

#define TT_MEDIAPLAYBACK_OFFSET_IGNORE   0xFFFFFFFF
 

Typedefs

typedef enum MediaFileStatus MediaFileStatus
 Status of media file being written to disk. More...
 
typedef enum AudioFileFormat AudioFileFormat
 Media file formats supported for muxed audio recordings. More...
 
typedef struct AudioFormat AudioFormat
 Struct describing the audio format used by a media file. More...
 
typedef struct MediaFileInfo MediaFileInfo
 Struct describing the audio and video format used by a media file. More...
 
typedef struct MediaFilePlayback MediaFilePlayback
 Properties for initializing or updating a file for media streaming. More...
 
typedef struct AudioInputProgress AudioInputProgress
 The progress of the audio currently being processed as audio input. More...
 

Enumerations

enum  MediaFileStatus {
  MFS_CLOSED = 0 , MFS_ERROR = 1 , MFS_STARTED = 2 , MFS_FINISHED = 3 ,
  MFS_ABORTED = 4 , MFS_PAUSED = 5 , MFS_PLAYING = 6
}
 Status of media file being written to disk. More...
 
enum  AudioFileFormat {
  AFF_NONE = 0 , AFF_CHANNELCODEC_FORMAT = 1 , AFF_WAVE_FORMAT = 2 , AFF_MP3_16KBIT_FORMAT = 3 ,
  AFF_MP3_32KBIT_FORMAT = 4 , AFF_MP3_64KBIT_FORMAT = 5 , AFF_MP3_128KBIT_FORMAT = 6 , AFF_MP3_256KBIT_FORMAT = 7
}
 Media file formats supported for muxed audio recordings. More...
 

Functions

TEAMTALKDLL_API TTBOOL TT_StartStreamingMediaFileToChannel (IN TTInstance *lpTTInstance, IN const TTCHAR *szMediaFilePath, IN const VideoCodec *lpVideoCodec)
 Stream media file to channel, e.g. avi-, wav- or MP3-file. More...
 
TEAMTALKDLL_API TTBOOL TT_StartStreamingMediaFileToChannelEx (IN TTInstance *lpTTInstance, IN const TTCHAR *szMediaFilePath, IN const MediaFilePlayback *lpMediaFilePlayback, IN const VideoCodec *lpVideoCodec)
 Stream media file to channel, e.g. avi, wav or MP3-file. More...
 
TEAMTALKDLL_API TTBOOL TT_UpdateStreamingMediaFileToChannel (IN TTInstance *lpTTInstance, IN const MediaFilePlayback *lpMediaFilePlayback, IN const VideoCodec *lpVideoCodec)
 Update active media file being streamed to channel. More...
 
TEAMTALKDLL_API TTBOOL TT_StopStreamingMediaFileToChannel (IN TTInstance *lpTTInstance)
 Stop streaming media file to channel. More...
 
TEAMTALKDLL_API INT32 TT_InitLocalPlayback (IN TTInstance *lpTTInstance, IN const TTCHAR *szMediaFilePath, IN const MediaFilePlayback *lpMediaFilePlayback)
 Play media file using settings from TTInstance. More...
 
TEAMTALKDLL_API TTBOOL TT_UpdateLocalPlayback (IN TTInstance *lpTTInstance, IN INT32 nPlaybackSessionID, IN const MediaFilePlayback *lpMediaFilePlayback)
 
TEAMTALKDLL_API TTBOOL TT_StopLocalPlayback (IN TTInstance *lpTTInstance, IN INT32 nPlaybackSessionID)
 
TEAMTALKDLL_API TTBOOL TT_GetMediaFileInfo (IN const TTCHAR *szMediaFilePath, OUT MediaFileInfo *lpMediaFileInfo)
 Get the properties of a media file. More...
 
TEAMTALKDLL_API VideoFrameTT_AcquireUserMediaVideoFrame (IN TTInstance *lpTTInstance, IN INT32 nUserID)
 Extract a user's media video frame for display. More...
 
TEAMTALKDLL_API TTBOOL TT_ReleaseUserMediaVideoFrame (IN TTInstance *lpTTInstance, IN VideoFrame *lpVideoFrame)
 Delete a user's video frame, acquired through TT_AcquireUserMediaVideoFrame(), so its allocated resources can be released. More...
 

Detailed Description

This section explains how to stream media files to channels.

Media files, mp3, avi, wmv, wma, etc. can be streamed to a channel and controlled separately from the voice and video capture input. Streaming a media file requires USERRIGHT_TRANSMIT_MEDIAFILE_AUDIO and/or USERRIGHT_TRANSMIT_MEDIAFILE_VIDEO.

The media formats supported by the TeamTalk DLL depends on the platform. On Windows the Windows Media Player's API is used to convert media files to TeamTalk's internal formats (i.e. Speex, OPUS and WebM). So whatever Windows Media Player can play should also be possible to stream using TeamTalk. On Mac and Linux avconv is used for converting media files which in similar way makes use of what the platform provides.

Use TT_GetMediaFileInfo() to see if the media file format is supported and what properties are used for audio and video.

To stream a media file to a channel call TT_StartStreamingMediaFileToChannel() and to stop the stream call TT_StopStreamingMediaFileToChannel(). The user receiving the media stream can control volume levels by calling TT_SetUserVolume() and TT_AcquireUserMediaVideoFrame() to obtain video frames.

Subscription of media files is controlled by SUBSCRIBE_MEDIAFILE.

Macro Definition Documentation

◆ TT_MEDIAPLAYBACK_OFFSET_IGNORE

#define TT_MEDIAPLAYBACK_OFFSET_IGNORE   0xFFFFFFFF

Specify this value as uOffsetMSec in MediaFilePlayback when calling TT_InitLocalPlayback() and TT_UpdateLocalPlayback() to ignore rewind or forward.

Definition at line 212 of file TeamTalk.h.

Typedef Documentation

◆ MediaFileStatus

Status of media file being written to disk.

See also
CLIENTEVENT_USER_RECORD_MEDIAFILE

◆ AudioFileFormat

Media file formats supported for muxed audio recordings.

See also
TT_StartRecordingMuxedAudioFile()

◆ AudioFormat

typedef struct AudioFormat AudioFormat

Struct describing the audio format used by a media file.

See also
TT_GetMediaFileInfo()
MediaFileInfo

◆ MediaFileInfo

typedef struct MediaFileInfo MediaFileInfo

Struct describing the audio and video format used by a media file.

See also
TT_GetMediaFile()

◆ MediaFilePlayback

◆ AudioInputProgress

The progress of the audio currently being processed as audio input.

See also
TT_InsertAudioBlock()

Enumeration Type Documentation

◆ MediaFileStatus

Status of media file being written to disk.

See also
CLIENTEVENT_USER_RECORD_MEDIAFILE
Enumerator
MFS_CLOSED 
MFS_ERROR 

Error while processing media file.

MFS_STARTED 

Started processing media file.

MFS_FINISHED 

Finished processing media file.

MFS_ABORTED 

Aborted processing of media file.

MFS_PAUSED 

Paused processing of media file.

MFS_PLAYING 

Playing media file with updated uElapsedMSec of MediaFileInfo.

Definition at line 736 of file TeamTalk.h.

◆ AudioFileFormat

Media file formats supported for muxed audio recordings.

See also
TT_StartRecordingMuxedAudioFile()
Enumerator
AFF_NONE 

Used to denote nothing selected.

AFF_CHANNELCODEC_FORMAT 

Store audio in the same format as the Channel's configured audio codec.

Audio is stored in OGG format. OGG format is supported by https://www.xiph.org/ogg and can be played using VLC media player http://www.videolan.org

Requires TeamTalk version 5.2.0.4730.

See also
TT_SetUserMediaStorageDir()
TT_StartRecordingMuxedAudioFile()
AFF_WAVE_FORMAT 

Store in PCM 16-bit wave format.

AFF_MP3_16KBIT_FORMAT 

Store in MP3-format.

AFF_MP3_32KBIT_FORMAT 
See also
AFF_MP3_16KBIT_FORMAT
AFF_MP3_64KBIT_FORMAT 
See also
AFF_MP3_16KBIT_FORMAT
AFF_MP3_128KBIT_FORMAT 
See also
AFF_MP3_16KBIT_FORMAT
AFF_MP3_256KBIT_FORMAT 
See also
AFF_MP3_16KBIT_FORMAT

Definition at line 757 of file TeamTalk.h.

Function Documentation

◆ TT_StartStreamingMediaFileToChannel()

TEAMTALKDLL_API TTBOOL TT_StartStreamingMediaFileToChannel ( IN TTInstance lpTTInstance,
IN const TTCHAR szMediaFilePath,
IN const VideoCodec lpVideoCodec 
)

Stream media file to channel, e.g. avi-, wav- or MP3-file.

See also
TT_StartStreamingMediaFileToChannelEx()

◆ TT_StartStreamingMediaFileToChannelEx()

TEAMTALKDLL_API TTBOOL TT_StartStreamingMediaFileToChannelEx ( IN TTInstance lpTTInstance,
IN const TTCHAR szMediaFilePath,
IN const MediaFilePlayback lpMediaFilePlayback,
IN const VideoCodec lpVideoCodec 
)

Stream media file to channel, e.g. avi, wav or MP3-file.

Call TT_GetMediaFileInfo() to get the properties of a media file, i.e. audio and video format.

The event CLIENTEVENT_STREAM_MEDIAFILE is posted when the media file starts streaming. The flags CLIENT_STREAM_AUDIO and/or CLIENT_STREAM_VIDEO will be set if the call is successful.

A media file is streamed using STREAMTYPE_MEDIAFILE_AUDIO and/or STREAMTYPE_MEDIAFILE_VIDEO. To subscribe/unsubscribe a media file being streamed use SUBSCRIBE_MEDIAFILE.

Streaming a media file requires USERRIGHT_TRANSMIT_MEDIAFILE_VIDEO and/or USERRIGHT_TRANSMIT_MEDIAFILE_AUDIO.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
szMediaFilePathFile path to media file.
lpMediaFilePlaybackPlayback settings to pause, seek and preprocess audio. If SPEEXDSP_AUDIOPREPROCESSOR then the echo cancellation part of SpeexDSP is unused. Only denoise and AGC settings are applied.
lpVideoCodecIf video file then specify output codec properties here, otherwise NULL.
See also
TT_UpdateStreamingMediaFileToChannel()
TT_StopStreamingMediaFileToChannel()
TT_InitLocalPlayback()

◆ TT_UpdateStreamingMediaFileToChannel()

TEAMTALKDLL_API TTBOOL TT_UpdateStreamingMediaFileToChannel ( IN TTInstance lpTTInstance,
IN const MediaFilePlayback lpMediaFilePlayback,
IN const VideoCodec lpVideoCodec 
)

Update active media file being streamed to channel.

While streaming a media file to a channel it's possible to pause, seek and manipulate audio preprocessing by passing new MediaFilePlayback properties.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
lpMediaFilePlaybackPlayback settings to pause, seek and preprocess audio. If SPEEXDSP_AUDIOPREPROCESSOR then the echo cancellation part of SpeexDSP is unused. Only denoise and AGC settings are applied.
lpVideoCodecIf video file then specify output codec properties here, otherwise NULL.
See also
TT_StartStreamingMediaFileToChannel()
TT_StopStreamingMediaFileToChannel()

◆ TT_StopStreamingMediaFileToChannel()

TEAMTALKDLL_API TTBOOL TT_StopStreamingMediaFileToChannel ( IN TTInstance lpTTInstance)

Stop streaming media file to channel.

This will clear the flags CLIENT_STREAM_AUDIO and/or CLIENT_STREAM_VIDEO.

See also
TT_StartStreamingMediaFileToChannel()

◆ TT_InitLocalPlayback()

TEAMTALKDLL_API INT32 TT_InitLocalPlayback ( IN TTInstance lpTTInstance,
IN const TTCHAR szMediaFilePath,
IN const MediaFilePlayback lpMediaFilePlayback 
)

Play media file using settings from TTInstance.

The sound system properties of the lpTTInstance will be used for playback, i.e. TT_SetSoundOutputMute(), TT_SetSoundOutputVolume() and TT_InitSoundOutputDevice().

Monitor progress of playback by checking for event CLIENTEVENT_LOCAL_MEDIAFILE.

Raw audio from local media playback can be retrieved using TT_EnableAudioBlockEvent().

A maximum of 16 simultaneous local media playbacks can be started.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
szMediaFilePathPath to media file.
lpMediaFilePlaybackPlayback settings to pause, seek and preprocess audio. If SPEEXDSP_AUDIOPREPROCESSOR then the echo cancellation part of SpeexDSP is unused. Only denoise and AGC settings are applied.
Returns
A Session ID, nPlaybackSessionID, for identifing the media playback session. If Session ID is <= 0 indicates an error.
See also
TT_UpdateLocalPlayback()
TT_StopLocalPlayback()
TT_StartStreamingMediaFileToChannel()

◆ TT_UpdateLocalPlayback()

TEAMTALKDLL_API TTBOOL TT_UpdateLocalPlayback ( IN TTInstance lpTTInstance,
IN INT32  nPlaybackSessionID,
IN const MediaFilePlayback lpMediaFilePlayback 
)

Update media file currently being played by TeamTalk instance.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nPlaybackSessionIDSession ID created by TT_InitLocalPlayback().
lpMediaFilePlaybackAudioPreprocessorType of AudioPreprocessor cannot be changed. It must be the same as used in TT_InitLocalPlayback().
See also
TT_InitLocalPlayback()
TT_StopLocalPlayback()
TT_UpdateStreamingMediaFileToChannel()

◆ TT_StopLocalPlayback()

TEAMTALKDLL_API TTBOOL TT_StopLocalPlayback ( IN TTInstance lpTTInstance,
IN INT32  nPlaybackSessionID 
)

Stop media file currently being played by TeamTalk instance.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nPlaybackSessionIDSession ID created by TT_InitLocalPlayback().
See also
TT_InitLocalPlayback()
TT_UpdateLocalPlayback()

◆ TT_GetMediaFileInfo()

TEAMTALKDLL_API TTBOOL TT_GetMediaFileInfo ( IN const TTCHAR szMediaFilePath,
OUT MediaFileInfo lpMediaFileInfo 
)

Get the properties of a media file.

Use this function to determine the audio and video properties of a media file, so the user knows what can be streamed.

See also
TT_StartStreamingMediaFileToChannel()

◆ TT_AcquireUserMediaVideoFrame()

TEAMTALKDLL_API VideoFrame* TT_AcquireUserMediaVideoFrame ( IN TTInstance lpTTInstance,
IN INT32  nUserID 
)

Extract a user's media video frame for display.

The VideoFrame extracted from the client instance will contain a pointer to the image's frame buffer, so a RGB32 bitmap can be displayed in a window control.

To release the acquired VideoFrame call TT_ReleaseUserMediaVideoFrame().

A media video frame comes from a user's STREAMTYPE_MEDIAFILE_VIDEO.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDThe user's ID. 0 for local user.
Returns
Returns video frame which will contain the image data. Note that it's the frameBuffer member of VideoFrame which will contain the image data allocated internally by TeamTalk. Returns NULL if no video frame could be acquired.
See also
TT_ReleaseUserMediaVideoFrame()

◆ TT_ReleaseUserMediaVideoFrame()

TEAMTALKDLL_API TTBOOL TT_ReleaseUserMediaVideoFrame ( IN TTInstance lpTTInstance,
IN VideoFrame lpVideoFrame 
)

Delete a user's video frame, acquired through TT_AcquireUserMediaVideoFrame(), so its allocated resources can be released.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
lpVideoFramePointer to VideoFrame which should be deallocated.
Returns
Returns TRUE if a video frame was successfully deallocated.
See also
TT_AcquireUserMediaVideoFrame()