TeamTalk 5 C-API DLL Version 5.18A

Classes | Macros | Typedefs | Enumerations | Functions
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 , AFF_MP3_320KBIT_FORMAT = 8 }
| 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 VideoFrame * | TT_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

typedef enum MediaFileStatus MediaFileStatus

Status of media file being written to disk.

See also
  CLIENTEVENT_USER_RECORD_MEDIAFILE

## ◆ AudioFileFormat

typedef enum AudioFileFormat 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

typedef struct MediaFilePlayback MediaFilePlayback

Properties for initializing or updating a file for media streaming.

See also
  TT_InitLocalPlayback()
  TT_UpdateLocalPlayback()
  TT_StartStreamingMediaFileToChannelEx()
  TT_UpdateStreamingMediaFileToChannel()

## ◆ AudioInputProgress

typedef struct AudioInputProgress AudioInputProgress

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

See also
  TT_InsertAudioBlock()

## Enumeration Type Documentation

## ◆ MediaFileStatus

enum 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 739 of file TeamTalk.h.

## ◆ AudioFileFormat

enum 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

AFF_MP3_320KBIT_FORMAT |

See also
  AFF_MP3_16KBIT_FORMAT

Definition at line 760 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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  szMediaFilePath | File path to media file.
  lpMediaFilePlayback | Playback 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.
  lpVideoCodec | If 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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  lpMediaFilePlayback | Playback 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.
  lpVideoCodec | If 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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  szMediaFilePath | Path to media file.
  lpMediaFilePlayback | Playback 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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nPlaybackSessionID | Session ID created by TT_InitLocalPlayback().
  lpMediaFilePlayback | AudioPreprocessorType 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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nPlaybackSessionID | Session 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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | The 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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  lpVideoFrame | Pointer to VideoFrame which should be deallocated.

Returns
  Returns TRUE if a video frame was successfully deallocated.

See also
  TT_AcquireUserMediaVideoFrame()