libgpac
Documentation of the core library of GPAC
DASH Client

MPEG-DASH and HLS Client. More...

+ Collaboration diagram for DASH Client:

Data Structures

struct  GF_DASHFileIO
 
struct  GF_DASHQualityInfo
 
struct  GF_DASHCustomAlgoInfo
 

Typedefs

typedef void * GF_DASHFileIOSession
 
typedef struct __dash_client GF_DashClient
 
typedef s32(* gf_dash_rate_adaptation) (void *udta, u32 group_idx, u32 base_group_idx, Bool force_lower_complexity, GF_DASHCustomAlgoInfo *stats)
 
typedef s32(* gf_dash_download_monitor) (void *udta, u32 group_idx, u32 bits_per_sec, u64 total_bytes, u64 bytes_done, u64 us_since_start, u32 buffer_dur_ms, u32 current_seg_dur)
 

Enumerations

enum  GF_DASHEventType {
  GF_DASH_EVENT_MANIFEST_INIT_ERROR , GF_DASH_EVENT_SELECT_GROUPS , GF_DASH_EVENT_PERIOD_SETUP_ERROR , GF_DASH_EVENT_CREATE_PLAYBACK ,
  GF_DASH_EVENT_DESTROY_PLAYBACK , GF_DASH_EVENT_SEGMENT_AVAILABLE , GF_DASH_EVENT_QUALITY_SWITCH , GF_DASH_EVENT_TIMESHIFT_UPDATE ,
  GF_DASH_EVENT_TIMESHIFT_OVERFLOW , GF_DASH_EVENT_CODEC_STAT_QUERY , GF_DASH_EVENT_ABORT_DOWNLOAD , GF_DASH_EVENT_CACHE_FULL ,
  GF_DASH_EVENT_END_OF_PERIOD
}
 
enum  GF_DASHInitialSelectionMode {
  GF_DASH_SELECT_QUALITY_LOWEST =0 , GF_DASH_SELECT_QUALITY_HIGHEST , GF_DASH_SELECT_BANDWIDTH_LOWEST , GF_DASH_SELECT_BANDWIDTH_HIGHEST ,
  GF_DASH_SELECT_BANDWIDTH_HIGHEST_TILES
}
 
enum  GF_DashDescriptorType {
  GF_MPD_DESC_ACCESSIBILITY , GF_MPD_DESC_AUDIOCONFIG , GF_MPD_DESC_CONTENT_PROTECTION , GF_MPD_DESC_ESSENTIAL_PROPERTIES ,
  GF_MPD_DESC_SUPPLEMENTAL_PROPERTIES , GF_MPD_DESC_FRAME_PACKING , GF_MPD_DESC_ROLE , GF_MPD_DESC_RATING ,
  GF_MPD_DESC_VIEWPOINT
}
 
enum  GF_DASHLowLatencyMode { GF_DASH_LL_DISABLE = 0 , GF_DASH_LL_STRICT , GF_DASH_LL_EARLY_FETCH }
 
enum  GF_DASHCrossASMode { GF_DASH_XAS_NONE = 0 , GF_DASH_XAS_CODEC , GF_DASH_XAS_ALL }
 
enum  GF_DASHTileAdaptationMode {
  GF_DASH_ADAPT_TILE_NONE =0 , GF_DASH_ADAPT_TILE_ROWS , GF_DASH_ADAPT_TILE_ROWS_REVERSE , GF_DASH_ADAPT_TILE_ROWS_MIDDLE ,
  GF_DASH_ADAPT_TILE_COLUMNS , GF_DASH_ADAPT_TILE_COLUMNS_REVERSE , GF_DASH_ADAPT_TILE_COLUMNS_MIDDLE , GF_DASH_ADAPT_TILE_CENTER ,
  GF_DASH_ADAPT_TILE_EDGES
}
 
enum  GF_DASHAdaptationAlgorithm {
  GF_DASH_ALGO_NONE = 0 , GF_DASH_ALGO_GPAC_LEGACY_RATE , GF_DASH_ALGO_GPAC_LEGACY_BUFFER , GF_DASH_ALGO_BBA0 ,
  GF_DASH_ALGO_BOLA_FINITE , GF_DASH_ALGO_BOLA_BASIC , GF_DASH_ALGO_BOLA_U , GF_DASH_ALGO_BOLA_O ,
  GF_DASH_ALGO_CUSTOM
}
 

Functions

GF_DashClientgf_dash_new (GF_DASHFileIO *dash_io, u32 max_cache_duration, s32 auto_switch_count, Bool keep_files, Bool disable_switching, GF_DASHInitialSelectionMode first_select_mode, u32 initial_time_shift_value)
 
void gf_dash_del (GF_DashClient *dash)
 
GF_Err gf_dash_open (GF_DashClient *dash, const char *manifest_url)
 
void gf_dash_close (GF_DashClient *dash)
 
GF_Err gf_dash_process (GF_DashClient *dash)
 
const char * gf_dash_get_url (GF_DashClient *dash)
 
Bool gf_dash_is_m3u8 (GF_DashClient *dash)
 
Bool gf_dash_is_smooth_streaming (GF_DashClient *dash)
 
void gf_dash_get_info (GF_DashClient *dash, const char **title, const char **source)
 
void gf_dash_switch_quality (GF_DashClient *dash, Bool switch_up)
 
Bool gf_dash_is_running (GF_DashClient *dash)
 
Bool gf_dash_is_in_setup (GF_DashClient *dash)
 
Double gf_dash_get_duration (GF_DashClient *dash)
 
GF_Err gf_dash_set_timeshift (GF_DashClient *dash, u32 ms_in_timeshift)
 
u32 gf_dash_get_group_count (GF_DashClient *dash)
 
GF_Err gf_dash_set_group_udta (GF_DashClient *dash, u32 group_index, void *udta)
 
void * gf_dash_get_group_udta (GF_DashClient *dash, u32 group_index)
 
Bool gf_dash_is_group_selected (GF_DashClient *dash, u32 group_index)
 
s32 gf_dash_group_has_dependent_group (GF_DashClient *dash, u32 group_idx)
 
u32 gf_dash_group_get_num_groups_depending_on (GF_DashClient *dash, u32 group_idx)
 
s32 gf_dash_get_dependent_group_index (GF_DashClient *dash, u32 group_idx, u32 group_depending_on_dep_idx)
 
Bool gf_dash_is_group_selectable (GF_DashClient *dash, u32 group_idx)
 
void gf_dash_group_select (GF_DashClient *dash, u32 group_idx, Bool select)
 
s32 gf_dash_group_get_id (GF_DashClient *dash, u32 group_idx)
 
const char * gf_dash_get_period_id (GF_DashClient *dash)
 
void gf_dash_enable_group_selection (GF_DashClient *dash, Bool enable)
 
Bool gf_dash_group_init_segment_is_media (GF_DashClient *dash, u32 group_idx)
 
void gf_dash_groups_set_language (GF_DashClient *dash, const char *lang_code_rfc_5646)
 
const char * gf_dash_group_get_segment_init_url (GF_DashClient *dash, u32 group_idx, u64 *start_range, u64 *end_range, const char **mime)
 
const char * gf_dash_group_get_segment_init_keys (GF_DashClient *dash, u32 group_idx, u32 *crypto_type, bin128 *key_IV)
 
const char * gf_dash_group_get_language (GF_DashClient *dash, u32 group_idx)
 
u32 gf_dash_group_get_audio_channels (GF_DashClient *dash, u32 group_idx)
 
u32 gf_dash_group_get_time_shift_buffer_depth (GF_DashClient *dash, u32 group_idx)
 
Double gf_dash_get_timeshift_buffer_pos (GF_DashClient *dash)
 
void gf_dash_group_set_codec_stat (GF_DashClient *dash, u32 group_idx, u32 avg_dec_time, u32 max_dec_time, u32 irap_avg_dec_time, u32 irap_max_dec_time, Bool codec_reset, Bool decode_only_rap)
 
void gf_dash_group_set_buffer_levels (GF_DashClient *dash, u32 group_idx, u32 buffer_min_ms, u32 buffer_max_ms, u32 buffer_occupancy_ms)
 
GF_Err gf_dash_group_set_max_buffer_playout (GF_DashClient *dash, u32 group_idx, u32 max_target_buffer_ms)
 
Bool gf_dash_group_enum_descriptor (GF_DashClient *dash, u32 group_idx, GF_DashDescriptorType desc_type, u32 role_idx, const char **desc_id, const char **desc_scheme, const char **desc_value)
 
GF_Err gf_dash_group_get_next_segment_location (GF_DashClient *dash, u32 group_idx, u32 dependent_representation_index, const char **url, u64 *start_range, u64 *end_range, s32 *switching_index, const char **switching_url, u64 *switching_start_range, u64 *switching_end_range, const char **original_url, Bool *has_next_segment, const char **key_url, bin128 *key_IV, u64 *utc)
 
GF_Err gf_dash_group_next_seg_info (GF_DashClient *dash, u32 group_idx, u32 dependent_representation_index, const char **seg_name, u32 *seg_number, GF_Fraction64 *seg_time, u32 *seg_dur_ms, const char **init_segment)
 
Bool gf_dash_group_loop_detected (GF_DashClient *dash, u32 group_idx)
 
Bool gf_dash_is_low_latency (GF_DashClient *dash, u32 group_idx)
 
GF_Err gf_dash_group_get_segment_duration (GF_DashClient *dash, u32 group_idx, u32 *duration, u32 *timescale)
 
const char * gf_dash_group_get_representation_id (GF_DashClient *dash, u32 group_idx)
 
Double gf_dash_group_get_start_range (GF_DashClient *dash, u32 group_idx)
 
void gf_dash_group_discard_segment (GF_DashClient *dash, u32 group_idx)
 
void gf_dash_set_group_done (GF_DashClient *dash, u32 group_idx, Bool done)
 
GF_Err gf_dash_group_get_presentation_time_offset (GF_DashClient *dash, u32 group_idx, u64 *presentation_time_offset, u32 *timescale)
 
Bool gf_dash_in_last_period (GF_DashClient *dash, Bool check_eos)
 
Bool gf_dash_get_group_done (GF_DashClient *dash, u32 group_idx)
 
u32 gf_dash_get_period_switch_status (GF_DashClient *dash)
 
void gf_dash_request_period_switch (GF_DashClient *dash)
 
Bool gf_dash_in_period_setup (GF_DashClient *dash)
 
void gf_dash_seek (GF_DashClient *dash, Double start_range)
 
Bool gf_dash_group_segment_switch_forced (GF_DashClient *dash, u32 group_idx)
 
GF_Err gf_dash_group_get_video_info (GF_DashClient *dash, u32 group_idx, u32 *max_width, u32 *max_height)
 
void gf_dash_group_seek (GF_DashClient *dash, u32 group_idx, Double seek_to)
 
void gf_dash_set_speed (GF_DashClient *dash, Double speed)
 
GF_Err gf_dash_group_check_bandwidth (GF_DashClient *dash, u32 group_idx, u32 bits_per_sec, u64 total_bytes, u64 bytes_done, u64 us_since_start)
 
void gf_dash_enable_utc_drift_compensation (GF_DashClient *dash, Bool estimate_utc_drift)
 
Bool gf_dash_is_dynamic_mpd (GF_DashClient *dash)
 
u32 gf_dash_get_min_buffer_time (GF_DashClient *dash)
 
u32 gf_dash_get_max_segment_duration (GF_DashClient *dash)
 
s32 gf_dash_get_utc_drift_estimate (GF_DashClient *dash)
 
void gf_dash_set_utc_shift (GF_DashClient *dash, s32 shift_utc_ms)
 
GF_Err gf_dash_set_max_resolution (GF_DashClient *dash, u32 width, u32 height, u8 max_display_bpp)
 
GF_Err gf_dash_set_min_timeout_between_404 (GF_DashClient *dash, u32 min_timeout_between_404)
 
GF_Err gf_dash_set_segment_expiration_threshold (GF_DashClient *dash, u32 expire_after_ms)
 
void gf_dash_debug_groups (GF_DashClient *dash, const u32 *groups_idx, u32 nb_groups)
 
void gf_dash_split_adaptation_sets (GF_DashClient *dash)
 
void gf_dash_set_low_latency_mode (GF_DashClient *dash, GF_DASHLowLatencyMode low_lat_mode)
 
void gf_dash_set_user_buffer (GF_DashClient *dash, u32 buffer_time_ms)
 
void gf_dash_set_switching_probe_count (GF_DashClient *dash, u32 switch_probe_count)
 
void gf_dash_set_agressive_adaptation (GF_DashClient *dash, Bool enable_agressive_switch)
 
void gf_dash_enable_single_range_llhls (GF_DashClient *dash, Bool enable_single_range)
 
void gf_dash_set_auto_switch (GF_DashClient *dash, s32 auto_switch_count, Bool auto_switch_loop)
 
void gf_dash_enable_cross_as_switch (GF_DashClient *dash, GF_DASHCrossASMode cross_as_mode)
 
u64 gf_dash_get_period_start (GF_DashClient *dash)
 
u64 gf_dash_get_period_duration (GF_DashClient *dash)
 
u32 gf_dash_group_get_num_qualities (GF_DashClient *dash, u32 group_idx)
 
u32 gf_dash_group_get_num_components (GF_DashClient *dash, u32 group_idx)
 
void gf_dash_disable_speed_adaptation (GF_DashClient *dash, Bool disable)
 
GF_Err gf_dash_group_get_quality_info (GF_DashClient *dash, u32 group_idx, u32 quality_idx, GF_DASHQualityInfo *quality)
 
char * gf_dash_group_get_template (GF_DashClient *dash, u32 group_idx, u32 *segment_timeline_timescale, const char **init_url, const char **hls_variant)
 
Bool gf_dash_get_automatic_switching (GF_DashClient *dash)
 
GF_Err gf_dash_set_automatic_switching (GF_DashClient *dash, Bool enable_switching)
 
GF_Err gf_dash_group_select_quality (GF_DashClient *dash, u32 group_idx, const char *ID, u32 q_idx)
 
s32 gf_dash_group_get_active_quality (GF_DashClient *dash, u32 group_idx)
 
void gf_dash_override_ntp (GF_DashClient *dash, u64 server_ntp)
 
void gf_dash_set_tile_adaptation_mode (GF_DashClient *dash, GF_DASHTileAdaptationMode mode, u32 tile_rate_decrease)
 
void gf_dash_disable_low_quality_tiles (GF_DashClient *dash, Bool disable_tiles)
 
GF_DASHTileAdaptationMode gf_dash_get_tile_adaptation_mode (GF_DashClient *dash)
 
Bool gf_dash_group_get_srd_max_size_info (GF_DashClient *dash, u32 group_idx, u32 *max_width, u32 *max_height)
 
Bool gf_dash_group_get_srd_info (GF_DashClient *dash, u32 group_idx, u32 *srd_id, u32 *srd_x, u32 *srd_y, u32 *srd_w, u32 *srd_h, u32 *srd_width, u32 *srd_height)
 
GF_Err gf_dash_group_set_quality_degradation_hint (GF_DashClient *dash, u32 group_idx, u32 quality_degradation_hint)
 
GF_Err gf_dash_group_set_visible_rect (GF_DashClient *dash, u32 group_idx, u32 min_x, u32 max_x, u32 min_y, u32 max_y, Bool is_gaze)
 
void gf_dash_ignore_xlink (GF_DashClient *dash, Bool ignore_xlink)
 
Bool gf_dash_all_groups_done (GF_DashClient *dash)
 
void gf_dash_set_period_xlink_query_string (GF_DashClient *dash, const char *query_string)
 
void gf_dash_set_chaining_mode (GF_DashClient *dash, u32 chaining_mode)
 
void gf_dash_set_algo (GF_DashClient *dash, GF_DASHAdaptationAlgorithm algo)
 
void gf_dash_set_group_download_state (GF_DashClient *dash, u32 group_idx, u32 dep_rep_idx, GF_Err err)
 
void gf_dash_group_store_stats (GF_DashClient *dash, u32 group_idx, u32 dep_rep_idx, u32 bytes_per_sec, u64 file_size, Bool is_broadcast, u64 us_since_start)
 
void gf_dash_set_suggested_presentation_delay (GF_DashClient *dash, s32 spd)
 
void gf_dash_set_mcast_ast_shift (GF_DashClient *dash, s32 ast_shift)
 
u32 gf_dash_get_min_wait_ms (GF_DashClient *dash)
 
s32 gf_dash_group_get_as_id (GF_DashClient *dash, u32 group_idx)
 
Bool gf_dash_group_has_init_segment (GF_DashClient *dash, u32 group_idx)
 
void gf_dash_group_get_sar (GF_DashClient *dash, u32 group_idx, GF_Fraction *sar)
 
void gf_dash_set_algo_custom (GF_DashClient *dash, void *udta, gf_dash_rate_adaptation algo_custom, gf_dash_download_monitor download_monitor_custom)
 

Variables

static const char *const GF_DASH_MPD_MIME_TYPES [] = { "application/dash+xml", "video/vnd.3gpp.mpd", "audio/vnd.3gpp.mpd", "video/vnd.mpeg.dash.mpd", "audio/vnd.mpeg.dash.mpd", NULL }
 
static const char *const GF_DASH_M3U8_MIME_TYPES [] = { "video/x-mpegurl", "audio/x-mpegurl", "application/x-mpegURL", "application/vnd.apple.mpegURL", NULL}
 
static const char *const GF_DASH_SMOOTH_MIME_TYPES [] = { "application/vnd.ms-sstr+xml", NULL}
 

Detailed Description


Data Structure Documentation

◆ GF_DASHQualityInfo

struct GF_DASHQualityInfo

DASH/HLS quality information structure

Data Fields
u32 bandwidth

bandwidth in bits per second

const char * ID

ID

const char * mime

mime type

const char * codec

codec parameter of mime type

u32 width

video width

u32 height

video width

Bool interlaced

video interlaced flag

u32 fps_num

video framerate numerator

u32 fps_den

video framerate denominator

u32 par_num

video sample aspect ratio numerator

u32 par_den

video sample aspect ratio denominator

u32 sample_rate

audio sample rate

u32 nb_channels

audio channel count

Bool disabled

disabled flag (not supported by DASH client)

Bool is_selected

selected flag

Double ast_offset

AST offset in seconds, 0 if not low latency

Double average_duration

average segment duration, 0 if unknown

const GF_List * seg_urls

list of segmentURLs if known, NULL otherwise. Used for onDemand profile to get segment sizes

const char * hls_variant_url

URL (relative) of variant playlist

u32 ssr

SSR flag, set to estimated num parts in SSR

◆ GF_DASHCustomAlgoInfo

struct GF_DASHCustomAlgoInfo

Information passed to DASH custom algorithm

Data Fields
u32 download_rate

last segment download rate in bits per second

u32 file_size

size of last downloaded segment

Double speed

current playback speed

Double max_available_speed

max supported playback speed according to associated decoder stats

u32 display_width

display width of the video in pixels, 0 if audio stream

u32 display_height

display height of the video in pixels, 0 if audio stream

u32 active_quality_idx

index of currently selected quality

u32 buffer_min_ms

minimum buffer level in milliseconds below witch rebuffer will happen

u32 buffer_max_ms

maximum buffer level allowed in milliseconds. Packets won't get dropped if overflow, but the algorithm should try not to overflow this buffer

u32 buffer_occupancy_ms

current buffer level in milliseconds

u32 quality_degradation_hint

degradation hint, 0 means no degradation, 100 means tile completely hidden

u32 total_rate

cumulated download rate of all active groups in bytes per seconds - 0 means all files are local

Typedef Documentation

◆ GF_DASHFileIOSession

typedef void* GF_DASHFileIOSession

structure used for all IO sessions for DASH

◆ GF_DashClient

typedef struct __dash_client GF_DashClient

DASH client object

◆ gf_dash_rate_adaptation

typedef s32(* gf_dash_rate_adaptation) (void *udta, u32 group_idx, u32 base_group_idx, Bool force_lower_complexity, GF_DASHCustomAlgoInfo *stats)

Callback function for custom rate adaptation

Parameters
udtauser data
group_idxindex of group to adapt
base_group_idxindex of associated base group if group is a dependent group
force_lower_complexityset to true if the dash client would like a lower complexity
statsstatistics for last downloaded segment
Returns
value can be:
  • the index of the new quality to select (as listed in group.reps[])
  • -1 to not take decision now and postpone it until dependent groups are done
  • -2 to disable quality
  • any other negative value means error

◆ gf_dash_download_monitor

typedef s32(* gf_dash_download_monitor) (void *udta, u32 group_idx, u32 bits_per_sec, u64 total_bytes, u64 bytes_done, u64 us_since_start, u32 buffer_dur_ms, u32 current_seg_dur)

Callback function for custom rate monitor, not final yet

Parameters
udtauser data
group_idxindex of group to adapt
bits_per_secestimated download rate (not premultiplied by playback speed)
total_bytessize of segment being downloaded, 0 if unknown
bytes_donebytes received for segment
us_since_startmicroseconds ellapse since segment was sheduled for download
buffer_dur_mscurrent buffer duration in milliseconds
current_seg_durduration of segment being downloaded, 0 if unknown
Returns
quality index (>=0) to switch to after abort, -1 to do nothing (no abort), -2 for internal algorithms having already setup the desired quality and requesting only abort

Enumeration Type Documentation

◆ GF_DASHEventType

DASH Event type. The DASH client communicates with the user through a callback mechanism using events

Enumerator
GF_DASH_EVENT_MANIFEST_INIT_ERROR 

event sent if an error occurs when setting up manifest

GF_DASH_EVENT_SELECT_GROUPS 

event sent before groups first segment is fetched - user shall decide which group to select at this point

GF_DASH_EVENT_PERIOD_SETUP_ERROR 

event sent if an error occurs during period setup - the download thread will exit at this point

GF_DASH_EVENT_CREATE_PLAYBACK 

event sent once the first segment of each selected group is fetched - user should load playback chain(s) at this point

GF_DASH_EVENT_DESTROY_PLAYBACK 

event sent when resetting groups at period switch or at exit - user should unload playback chain(s) at this point

GF_DASH_EVENT_SEGMENT_AVAILABLE 

event sent once a new segment becomes available

GF_DASH_EVENT_QUALITY_SWITCH 

event sent when quality has been switched for the given group

GF_DASH_EVENT_TIMESHIFT_UPDATE 

position in timeshift buffer has changed (eg, paused)

GF_DASH_EVENT_TIMESHIFT_OVERFLOW 

event sent when timeshift buffer is overflown - the group_idx param contains the max number of dropped segments of all representations dropped by the client, or -1 if play pos is ahead of live

GF_DASH_EVENT_CODEC_STAT_QUERY 

event sent when we need the decoding statistics

GF_DASH_EVENT_ABORT_DOWNLOAD 

event sent when no threading to trigger segment download abort

GF_DASH_EVENT_CACHE_FULL 

event sent whenever cache is full, to allow client to dispatch any segment

GF_DASH_EVENT_END_OF_PERIOD 

event sent when all groups are done in a period - if group_idx is 1, this announces a time discontinuity for next period

◆ GF_DASHInitialSelectionMode

Quality selection mode of initial segments

Enumerator
GF_DASH_SELECT_QUALITY_LOWEST 

selects the lowest quality when starting - if one of the representation does not have video (HLS), it may be selected

GF_DASH_SELECT_QUALITY_HIGHEST 

selects the highest quality when starting

GF_DASH_SELECT_BANDWIDTH_LOWEST 

selects the lowest bandwidth when starting - if one of the representation does not have video (HLS), it will NOT be selected

GF_DASH_SELECT_BANDWIDTH_HIGHEST 

selects the highest bandwidth when starting - for tiles all low priority tiles will have the lower (below max) bandwidth selected

GF_DASH_SELECT_BANDWIDTH_HIGHEST_TILES 

selects the highest bandwidth when starting - for tiles all low priority tiles will have their lowest bandwidth selected

◆ GF_DashDescriptorType

DASH descriptor types

Enumerator
GF_MPD_DESC_ACCESSIBILITY 

Accessibility descriptor

GF_MPD_DESC_AUDIOCONFIG 

Audio config descriptor

GF_MPD_DESC_CONTENT_PROTECTION 

Content Protection descriptor

GF_MPD_DESC_ESSENTIAL_PROPERTIES 

Essential Property descriptor

GF_MPD_DESC_SUPPLEMENTAL_PROPERTIES 

Supplemental Property descriptor

GF_MPD_DESC_FRAME_PACKING 

Frame packing descriptor

GF_MPD_DESC_ROLE 

Role descriptor

GF_MPD_DESC_RATING 

Rating descriptor

GF_MPD_DESC_VIEWPOINT 

Viewpoint descriptor

◆ GF_DASHLowLatencyMode

low latency mode of dash client

Enumerator
GF_DASH_LL_DISABLE 

disable low latency

GF_DASH_LL_STRICT 

strict respect of segment availability start time

GF_DASH_LL_EARLY_FETCH 

allow fetching segments earlier than their availability start time in case of empty demux

◆ GF_DASHCrossASMode

Cross Adaptation-set switching mdoe

Enumerator
GF_DASH_XAS_NONE 

cross adaptation set is disabled

GF_DASH_XAS_CODEC 

cross adaptation set is enabled and only switches on the same codec

GF_DASH_XAS_ALL 

cross adaptation set is enabled and can switch to any codec

◆ GF_DASHTileAdaptationMode

Tile adaptation mode This mode specifies how bitrate is allocated across tiles of the same video

Enumerator
GF_DASH_ADAPT_TILE_NONE 

each tile receives the same amount of bitrate (default strategy)

GF_DASH_ADAPT_TILE_ROWS 

bitrate decreases for each row of tiles starting from the top, same rate for each tile on the row

GF_DASH_ADAPT_TILE_ROWS_REVERSE 

bitrate decreases for each row of tiles starting from the bottom, same rate for each tile on the row

GF_DASH_ADAPT_TILE_ROWS_MIDDLE 

bitrate decreased for top and bottom rows only, same rate for each tile on the row

GF_DASH_ADAPT_TILE_COLUMNS 

bitrate decreases for each column of tiles starting from the left, same rate for each tile on the column

GF_DASH_ADAPT_TILE_COLUMNS_REVERSE 

bitrate decreases for each column of tiles starting from the right, same rate for each tile on the column

GF_DASH_ADAPT_TILE_COLUMNS_MIDDLE 

bitrate decreased for left and right columns only, same rate for each tile on the column

GF_DASH_ADAPT_TILE_CENTER 

bitrate decreased for all tiles on the edge of the picture

GF_DASH_ADAPT_TILE_EDGES 

bitrate decreased for all tiles on the center of the picture

◆ GF_DASHAdaptationAlgorithm

DASH client adaptation algorithm

Enumerator
GF_DASH_ALGO_NONE 

no adaptation

GF_DASH_ALGO_GPAC_LEGACY_RATE 

GPAC rate-based adaptation

GF_DASH_ALGO_GPAC_LEGACY_BUFFER 

GPAC buffer-based adaptation

GF_DASH_ALGO_BBA0 

BBA-0

GF_DASH_ALGO_BOLA_FINITE 

BOLA finite

GF_DASH_ALGO_BOLA_BASIC 

BOLA basic

GF_DASH_ALGO_BOLA_U 

BOLA-U

GF_DASH_ALGO_BOLA_O 

BOLA-O

GF_DASH_ALGO_CUSTOM 

Custom

Function Documentation

◆ gf_dash_new()

GF_DashClient* gf_dash_new ( GF_DASHFileIO *  dash_io,
u32  max_cache_duration,
s32  auto_switch_count,
Bool  keep_files,
Bool  disable_switching,
GF_DASHInitialSelectionMode  first_select_mode,
u32  initial_time_shift_value 
)

create a new DASH client

Parameters
dash_ioDASH callbacks to the user
max_cache_durationmaximum duration in milliseconds for the cached media. If less than
mpd@minBufferTime
,
mpd@minBufferTime
is used
auto_switch_countforces representation switching (quality up if positive, down if negative) every auto_switch_count segments, set to 0 to disable
keep_filesdo not delete files from the cache
disable_switchingturn off bandwidth switching algorithm
first_select_modeindicates which representation to select upon startup
initial_time_shift_valuesets initial buffering: if between 0 and 100, this is a percentage of the time shift window of the session. If greater than 100, this is a time shift in milliseconds.
Returns
a new DASH client

◆ gf_dash_del()

void gf_dash_del ( GF_DashClient dash)

destroys a DASH client

Parameters
dashthe target dash clien

◆ gf_dash_open()

GF_Err gf_dash_open ( GF_DashClient dash,
const char *  manifest_url 
)

opens the DASH client for the specific manifest file

Parameters
dashthe target dash client
manifest_urlthe URL of the manifest to open
Returns
error if any

◆ gf_dash_close()

void gf_dash_close ( GF_DashClient dash)

closes the dash client

Parameters
dashthe target dash client

◆ gf_dash_process()

GF_Err gf_dash_process ( GF_DashClient dash)

for unthreaded session, executes DASH logic

Parameters
dashthe target dash client
Returns
error if any, GF_EOS on end of session

◆ gf_dash_get_url()

const char* gf_dash_get_url ( GF_DashClient dash)

returns URL of the DASH manifest file

Parameters
dashthe target dash client
Returns
the currently loaded manifest

◆ gf_dash_is_m3u8()

Bool gf_dash_is_m3u8 ( GF_DashClient dash)

tells whether we are playing some Apple HLS M3U8

Parameters
dashthe target dash client
Returns
GF_TRUE if the manifest is M3U8

◆ gf_dash_is_smooth_streaming()

Bool gf_dash_is_smooth_streaming ( GF_DashClient dash)

tells whether we are playing some MS SmoothStreaming

Parameters
dashthe target dash client
Returns
GF_TRUE if the manifest is SmoothStreaming

◆ gf_dash_get_info()

void gf_dash_get_info ( GF_DashClient dash,
const char **  title,
const char **  source 
)

gets title and source for this MPD

Parameters
dashthe target dash client
titleset to the title of the manifest (may be NULL)
sourceset to the source of the manifest (may be NULL)

◆ gf_dash_switch_quality()

void gf_dash_switch_quality ( GF_DashClient dash,
Bool  switch_up 
)

switches quality up or down

Parameters
dashthe target dash client
switch_upindicates if the quality should be increased (GF_TRUE) or decreased (GF_FALSE)

◆ gf_dash_is_running()

Bool gf_dash_is_running ( GF_DashClient dash)

indicates whether the DASH client is running or not

Parameters
dashthe target dash client
Returns
GF_TRUE if the session is still active, GF_FALSE otherwise

◆ gf_dash_is_in_setup()

Bool gf_dash_is_in_setup ( GF_DashClient dash)

indicates whether the DASH client is in setup stage (sloving periods, destroying or creating playback chain) or not

Parameters
dashthe target dash client
Returns
GF_TRUE if the session is in setup, GF_FALSE otherwise

◆ gf_dash_get_duration()

Double gf_dash_get_duration ( GF_DashClient dash)

gets duration of the presentation

Parameters
dashthe target dash client
Returns
the duration in second of the session

◆ gf_dash_set_timeshift()

GF_Err gf_dash_set_timeshift ( GF_DashClient dash,
u32  ms_in_timeshift 
)

sets timeshift for the presentation - this function does not trigger a seek, this has to be done by the caller

Parameters
dashthe target dash client
ms_in_timeshiftif between 0 and 100, this is a percentage of the time shift window of the session. If greater than 100, this is a time shift in milliseconds
Returns
error if any

◆ gf_dash_get_group_count()

u32 gf_dash_get_group_count ( GF_DashClient dash)

returns the number of groups. A group is a set of media resources that are alternate of each other in terms of bandwidth/quality

Parameters
dashthe target dash client
Returns
the number of groups in the active session

◆ gf_dash_set_group_udta()

GF_Err gf_dash_set_group_udta ( GF_DashClient dash,
u32  group_index,
void *  udta 
)

associates user data (or NULL) with a given group

Parameters
dashthe target dash client
group_indexthe 0-based index of the target group
udtathe opaque data to associate to the group
Returns
error if any

◆ gf_dash_get_group_udta()

void* gf_dash_get_group_udta ( GF_DashClient dash,
u32  group_index 
)

returns the user data associated with this group

Parameters
dashthe target dash client
group_indexthe 0-based index of the target group
Returns
the opaque data to associate to the group

◆ gf_dash_is_group_selected()

Bool gf_dash_is_group_selected ( GF_DashClient dash,
u32  group_index 
)

indicates whether a group is selected for playback or not. Currently groups cannot be selected during playback

Parameters
dashthe target dash client
group_indexthe 0-based index of the target group
Returns
GF_TRUE if the group is selected for playback/download

◆ gf_dash_group_has_dependent_group()

s32 gf_dash_group_has_dependent_group ( GF_DashClient dash,
u32  group_idx 
)

indicates whether this group is dependent on another group (because representations are). If this is the case, all representations of this group will be made available through the base group (and has_next_segment flag) if the group is selected. returns -1 if not dependent on another group, otherwise return dependent group index

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
-1 if the group does not depend on another group, otherwise returns the dependent group index

◆ gf_dash_group_get_num_groups_depending_on()

u32 gf_dash_group_get_num_groups_depending_on ( GF_DashClient dash,
u32  group_idx 
)

gives the number of groups depending on this one for decoding

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
the number of other groups depending on this group

◆ gf_dash_get_dependent_group_index()

s32 gf_dash_get_dependent_group_index ( GF_DashClient dash,
u32  group_idx,
u32  group_depending_on_dep_idx 
)

gets the index of the depending_on group with the specified group_depending_on_dep_idx (between 0 and gf_dash_group_get_num_groups_depending_on -1)

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
group_depending_on_dep_idxthe 0-based index of the queried dependent group
Returns
the index of the depending_on group

◆ gf_dash_is_group_selectable()

Bool gf_dash_is_group_selectable ( GF_DashClient dash,
u32  group_idx 
)

indicates whether a group can be selected for playback or not. Some groups may have been disabled because of non supported features

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
GF_TRUE if the group can be selected for playback, GF_FALSE otherwise

◆ gf_dash_group_select()

void gf_dash_group_select ( GF_DashClient dash,
u32  group_idx,
Bool  select 
)

selects a group for playback. If group selection is enabled, other groups are alternate to this group (through the group attribute), they are automatically deselected

Seeking is NOT performed, it is the responsability to call gf_dash_group_seek - this can be called before or after selecting

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
selectif GF_TRUE, will select this group and disable any alternate group. If GF_FALSE, only deselects the group

◆ gf_dash_group_get_id()

s32 gf_dash_group_get_id ( GF_DashClient dash,
u32  group_idx 
)

gets group ID (through the group attribute), -1 if undefined

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
ID of the group

◆ gf_dash_get_period_id()

const char* gf_dash_get_period_id ( GF_DashClient dash)

gets cuirrent period ID

Parameters
dashthe target dash client
Returns
ID of the current period or NULL

◆ gf_dash_enable_group_selection()

void gf_dash_enable_group_selection ( GF_DashClient dash,
Bool  enable 
)

enables group selection through the group attribute

Parameters
dashthe target dash client
enableif GF_TRUE, group selection will be done whenever selecting a new group

◆ gf_dash_group_init_segment_is_media()

Bool gf_dash_group_init_segment_is_media ( GF_DashClient dash,
u32  group_idx 
)

checks if first segment (used to initialize) was an init segment or the first in a sequence (aka M2TS)

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
GF_TRUE if first segment was a media segment

◆ gf_dash_groups_set_language()

void gf_dash_groups_set_language ( GF_DashClient dash,
const char *  lang_code_rfc_5646 
)

performs selection of representations based on language code

Parameters
dashthe target dash client
lang_code_rfc_5646the language code used by the default group selection

◆ gf_dash_group_get_segment_init_url()

const char* gf_dash_group_get_segment_init_url ( GF_DashClient dash,
u32  group_idx,
u64 start_range,
u64 end_range,
const char **  mime 
)

returns the URL of the first media resource to play (init segment or first media segment depending on format). start_range and end_range are optional

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
start_rangeset to the byte start offset in the init segment
end_rangeset to the byte end offset in the init segment
mimethe mime type of the init segment
Returns
URL of the init segment (can be a relative path if manifest is a local file)

◆ gf_dash_group_get_segment_init_keys()

const char* gf_dash_group_get_segment_init_keys ( GF_DashClient dash,
u32  group_idx,
u32 crypto_type,
bin128 key_IV 
)

returns the URL and IV associated with the first media segment if any (init segment or first media segment depending on format). This is used for full segment encryption modes of MPEG-2 TS segments. key_IV is optional

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
crypto_typeset to 0 if no encryption in segments, 1 if full segment encryption, 2 if CENC/per-sample encryption is used - may be NULL
key_IVset to the IV used for the first media segment (can be NULL)
Returns
the key URL of the first media segment, either a URN or a resolved URL

◆ gf_dash_group_get_language()

const char* gf_dash_group_get_language ( GF_DashClient dash,
u32  group_idx 
)

returns the language of the group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
the language of the group or NULL if no language associated

◆ gf_dash_group_get_audio_channels()

u32 gf_dash_group_get_audio_channels ( GF_DashClient dash,
u32  group_idx 
)

returns the number of audio channelsof the group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
the number of audio channels, or 0 if not audio or unspecified

◆ gf_dash_group_get_time_shift_buffer_depth()

u32 gf_dash_group_get_time_shift_buffer_depth ( GF_DashClient dash,
u32  group_idx 
)

gets time shift buffer depth of the group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
time shift buffer depth in ms of the group, -1 means infinity

◆ gf_dash_get_timeshift_buffer_pos()

Double gf_dash_get_timeshift_buffer_pos ( GF_DashClient dash)

gets current time in time shift buffer This functions retrieves the maximum value (further in the past) of all selected/active groups

Parameters
dashthe target dash client
Returns
current time in timeshift buffer in seconds - 0 means 'live point'

◆ gf_dash_group_set_codec_stat()

void gf_dash_group_set_codec_stat ( GF_DashClient dash,
u32  group_idx,
u32  avg_dec_time,
u32  max_dec_time,
u32  irap_avg_dec_time,
u32  irap_max_dec_time,
Bool  codec_reset,
Bool  decode_only_rap 
)

sets codec statistics of a group for playback rate adjustment

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
avg_dec_timeaverage decode time in microseconds of a frame, 0 if unknown
max_dec_timemaximum decode time in microseconds of a frame, 0 if unknown
irap_avg_dec_timeaverage decode time of SAP 1/2/3 pictures in microseconds of a frame, 0 if unknown
irap_max_dec_timemaximum decode time of SAP 1/2/3 pictures in microseconds of a frame, 0 if unknown
codec_resetindicates a codec reset is pending (pipeline flush is needed before reinit)
decode_only_rapindicates only SAP1/2/3 are currently being decoded. This may trigger a switch to a trick mode representation

◆ gf_dash_group_set_buffer_levels()

void gf_dash_group_set_buffer_levels ( GF_DashClient dash,
u32  group_idx,
u32  buffer_min_ms,
u32  buffer_max_ms,
u32  buffer_occupancy_ms 
)

sets buffer levels of a group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
buffer_min_msminimum buffer in milliseconds (pipeline would rebuffer below this level)
buffer_max_msmaximum buffer in milliseconds (pipeline would block above this level)
buffer_occupancy_mscurrent buffer occupancy in milliseconds

◆ gf_dash_group_set_max_buffer_playout()

GF_Err gf_dash_group_set_max_buffer_playout ( GF_DashClient dash,
u32  group_idx,
u32  max_target_buffer_ms 
)

indicates the buffer time in ms after which the player resumes playback. This value is less or equal to the buffer_max_ms indicated in gf_dash_group_set_buffer_levels

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
max_target_buffer_msbuffer in milliseconds above which pipeline resumes after a rebuffering event
Returns
error if any

◆ gf_dash_group_enum_descriptor()

Bool gf_dash_group_enum_descriptor ( GF_DashClient dash,
u32  group_idx,
GF_DashDescriptorType  desc_type,
u32  role_idx,
const char **  desc_id,
const char **  desc_scheme,
const char **  desc_value 
)

enumerates descriptors of the given type

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
desc_typetype of descriptor being checked
role_idxindex of the descriptor being checked for this type
desc_idset to the ID of the descriptor if found (optional, may be NULL)
desc_schemeset to the scheme of the descriptor if found (optional, may be NULL)
desc_valueset to the desc_value of the descriptor if found (optional, may be NULL)
Returns
GF_TRUE if descriptor is found, GF_FALSE otherwise

◆ gf_dash_group_get_next_segment_location()

GF_Err gf_dash_group_get_next_segment_location ( GF_DashClient dash,
u32  group_idx,
u32  dependent_representation_index,
const char **  url,
u64 start_range,
u64 end_range,
s32 switching_index,
const char **  switching_url,
u64 switching_start_range,
u64 switching_end_range,
const char **  original_url,
Bool has_next_segment,
const char **  key_url,
bin128 key_IV,
u64 utc 
)

returns the URL and byte range of the next media resource to play in this group.

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
dependent_representation_indexindex of the dependent representation to query, 0-based
urlset to the URL of the next segment
start_rangeset to the start byte offset in the segment (optional, may be NULL)
end_rangeset to the end byte offset in the segment (optional, may be NULL)
switching_indexset to the quality index of the segment (optional, may be NULL)
switching_urlset to the URL of the switching segment if needed (optional, may be NULL)
switching_start_rangeset to start byte offset of the switching segment if needed (optional, may be NULL)
switching_end_rangeset to end byte offset of the switching segment if needed (optional, may be NULL)
original_urlset to original URL value of the segment (optional, may be NULL)
has_next_segmentset to GF_TRUE if next segment location is known (unthreaded mode) or next segment is downloaded (threaded mode) (optional, may be NULL)
key_urlset to the key URL of the next segment for MPEG-2 TS full segment encryption (optional, may be NULL). The URL is either a URN or a resolved URL
key_IVset to the key initialization vector of the next segment for MPEG-2 TS full segment encryption (optional, may be NULL)
utcset to UTC mapping for first sample of segment, 0 if none defined
Returns
GF_BUFFER_TOO_SMALL if no segment found, GF_EOS if end of session, GF_URL_REMOVED if segment is disabled (but all output info is OK, this can be ignored and considered as GF_OK by the user) or error if any

◆ gf_dash_group_next_seg_info()

GF_Err gf_dash_group_next_seg_info ( GF_DashClient dash,
u32  group_idx,
u32  dependent_representation_index,
const char **  seg_name,
u32 seg_number,
GF_Fraction64 seg_time,
u32 seg_dur_ms,
const char **  init_segment 
)

gets some info on the segment

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
dependent_representation_indexindex of the dependent representation to query, 0-based
seg_nameset to the segment name, without base url - optional, may be NULL
seg_numberset to the segment number for $Number$ addressing - optional, may be NULL
seg_timeset to the segment start time - optional, may be NULL
seg_dur_msset to the segment estimated duration in ms - optional, may be NULL
init_segmentset to the init segment name, without base url - optional, may be NULL
Returns
error if any, GF_BUFFER_TOO_SMALL if no segments queued for download

◆ gf_dash_group_loop_detected()

Bool gf_dash_group_loop_detected ( GF_DashClient dash,
u32  group_idx 
)

checks if loop was detected in playback. This is mostly used for broadcast (eMBMS, ROUTE) based on pcap replay.

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
GF_TRUE if segment numbers loop was detected

◆ gf_dash_is_low_latency()

Bool gf_dash_is_low_latency ( GF_DashClient dash,
u32  group_idx 
)

checks if group is using low latency delivery.

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
GF_TRUE if low latency is used, GF_FALSE otherwise

◆ gf_dash_group_get_segment_duration()

GF_Err gf_dash_group_get_segment_duration ( GF_DashClient dash,
u32  group_idx,
u32 duration,
u32 timescale 
)

gets average duration of segments for the current rep.

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
durationset to average segment duration
timescaleset to timescale used to exprss duration
Returns
error if any

◆ gf_dash_group_get_representation_id()

const char* gf_dash_group_get_representation_id ( GF_DashClient dash,
u32  group_idx 
)

gets ID of active representaion.

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
ID of representation, NULL if error

◆ gf_dash_group_get_start_range()

Double gf_dash_group_get_start_range ( GF_DashClient dash,
u32  group_idx 
)

returns number of seconds at which playback shall start for the group in the current period. The first segment available for the period will be so that gf_dash_group_get_start_range is in this range after the caller adjusts it with PTO (eg the returned time is in period timeline, not media timeline)

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
media playback start range in seconds

◆ gf_dash_group_discard_segment()

void gf_dash_group_discard_segment ( GF_DashClient dash,
u32  group_idx 
)

discards the first media resource in the queue of this group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group

◆ gf_dash_set_group_done()

void gf_dash_set_group_done ( GF_DashClient dash,
u32  group_idx,
Bool  done 
)

indicates to the DASH engine that the group playback has been stopped by the user

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
donemark group as done if GF_TRUE, or not done if GF_FALSE

◆ gf_dash_group_get_presentation_time_offset()

GF_Err gf_dash_group_get_presentation_time_offset ( GF_DashClient dash,
u32  group_idx,
u64 presentation_time_offset,
u32 timescale 
)

gets presentationTimeOffset and timescale for the active representation

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
presentation_time_offsetset to the presentation time offset for the group
timescaleset to the timescale used to represent the presentation time offset
Returns
error if any

◆ gf_dash_in_last_period()

Bool gf_dash_in_last_period ( GF_DashClient dash,
Bool  check_eos 
)

checks if the session is in the last period

Parameters
dashthe target dash client
check_eosif GF_TRUE, return GF_TRUE only if the last period is known to be the last one (not an open period in live)
Returns
GF_TRUE if the playback position is in the last period of the presentation

◆ gf_dash_get_group_done()

Bool gf_dash_get_group_done ( GF_DashClient dash,
u32  group_idx 
)

checks if the group is playing

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
GF_TRUE if group is done playing

◆ gf_dash_get_period_switch_status()

u32 gf_dash_get_period_switch_status ( GF_DashClient dash)

gets current period switching status for the session.

Parameters
dashthe target dash client
Returns
possible values: 1 if the period switching has been requested (due to seeking), 2 if the switching is in progress (all groups will soon be destroyed and plyback will be stopped and restarted) 0 if no switching is requested

◆ gf_dash_request_period_switch()

void gf_dash_request_period_switch ( GF_DashClient dash)

request period switch - this is typically called when the media engine signals that no more data is available for playback

Parameters
dashthe target dash client

◆ gf_dash_in_period_setup()

Bool gf_dash_in_period_setup ( GF_DashClient dash)

checks if the client is in a period setup state

Parameters
dashthe target dash client
Returns
GF_TRUE if the DASH engine is currently setting up a period (creating groups and fetching initial segments)

◆ gf_dash_seek()

void gf_dash_seek ( GF_DashClient dash,
Double  start_range 
)

seeks playback to the given time. If period changes, all playback is stopped and restarted If the session is dynamic (live), the start_range is ignored and recomputed from current UTC clock to be at the live point. If timeshifting is desired, use gf_dash_set_timeshift before seeking

Parameters
dashthe target dash client
start_rangethe desired seek time in seconds

◆ gf_dash_group_segment_switch_forced()

Bool gf_dash_group_segment_switch_forced ( GF_DashClient dash,
u32  group_idx 
)

checks if seeking time is in the previously playing segment

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
GF_TRUE if the seek request was in a different segment than the previously playing one

◆ gf_dash_group_get_video_info()

GF_Err gf_dash_group_get_video_info ( GF_DashClient dash,
u32  group_idx,
u32 max_width,
u32 max_height 
)

gets video info for this group if video

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
max_widthset to the maximum width in the group
max_heightset to the maximum height in the group
Returns
error if any

◆ gf_dash_group_seek()

void gf_dash_group_seek ( GF_DashClient dash,
u32  group_idx,
Double  seek_to 
)

seeks only a given group - results are undefined if the seek operation triggers a period switch

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
seek_tothe desired seek time in seconds

◆ gf_dash_set_speed()

void gf_dash_set_speed ( GF_DashClient dash,
Double  speed 
)

sets playback speed of the session. Speed is used in adaptation logic

Parameters
dashthe target dash client
speedcurrent playback speed

◆ gf_dash_group_check_bandwidth()

GF_Err gf_dash_group_check_bandwidth ( GF_DashClient dash,
u32  group_idx,
u32  bits_per_sec,
u64  total_bytes,
u64  bytes_done,
u64  us_since_start 
)

updates media bandwidth for the given group. Only allowed for groups without dependencies to other groups

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
bits_per_seccurrent download rate in bits per seconds
total_bytestotal size of segment being downloaded
bytes_donenumber of bytes already downloaded in current segment
us_since_starttime elapsed in microseconds since segment has been scheduled for download
Returns
error if any

◆ gf_dash_enable_utc_drift_compensation()

void gf_dash_enable_utc_drift_compensation ( GF_DashClient dash,
Bool  estimate_utc_drift 
)

enables UTC drift computation using HTTP header "Server-UTC: UTC", where UTC is in ms

Parameters
dashthe target dash client
estimate_utc_driftif GF_TRUE, enables UTC drift compensation, otherwise disables it

◆ gf_dash_is_dynamic_mpd()

Bool gf_dash_is_dynamic_mpd ( GF_DashClient dash)

checks if session is dynamic offering (live)

Parameters
dashthe target dash client
Returns
GF_TRUE if MPD is dynamic, GF_FALSE otherwise

◆ gf_dash_get_min_buffer_time()

u32 gf_dash_get_min_buffer_time ( GF_DashClient dash)

gets minimum buffer time of session indicated in MPD

Parameters
dashthe target dash client
Returns
minimum buffer time in ms

◆ gf_dash_get_max_segment_duration()

u32 gf_dash_get_max_segment_duration ( GF_DashClient dash)

gets the maximum segment duration in session

Parameters
dashthe target dash client
Returns
the maximum segment duration in ms

◆ gf_dash_get_utc_drift_estimate()

s32 gf_dash_get_utc_drift_estimate ( GF_DashClient dash)

gets the difference between the local UTC clock and the one reported by the server

Parameters
dashthe target dash client
Returns
difference in milliseconds

◆ gf_dash_set_utc_shift()

void gf_dash_set_utc_shift ( GF_DashClient dash,
s32  shift_utc_ms 
)

shifts UTC clock of server by shift_utc_ms so that new UTC in MPD is old + shift_utc_ms

Parameters
dashthe target dash client
shift_utc_msUTC clock shift in milliseconds. A positive value will move the clock in the future, a negative value in the past

◆ gf_dash_set_max_resolution()

GF_Err gf_dash_set_max_resolution ( GF_DashClient dash,
u32  width,
u32  height,
u8  max_display_bpp 
)

sets max video display capabilities

Parameters
dashthe target dash client
widththe maximum width of the display
heightthe maximum height of the display
max_display_bppthe maximum bits per pixel of the display
Returns
error if any

◆ gf_dash_set_min_timeout_between_404()

GF_Err gf_dash_set_min_timeout_between_404 ( GF_DashClient dash,
u32  min_timeout_between_404 
)

sets min time in ms between a 404 and the next request on the same group. The default value is 500 ms.

Parameters
dashthe target dash client
min_timeout_between_404minimum delay in milliseconds between retries
Returns
error if any

◆ gf_dash_set_segment_expiration_threshold()

GF_Err gf_dash_set_segment_expiration_threshold ( GF_DashClient dash,
u32  expire_after_ms 
)

sets time in ms after which 404 request for a segment will indicate segment lost. The client always retries for segment availability time + segment duration. This allows extending slightly the probe time (used when segment durations varies, or for VBR broadcast). The default value is 100 ms.

Parameters
dashthe target dash client
expire_after_msdelay in milliseconds
Returns
error if any

◆ gf_dash_debug_groups()

void gf_dash_debug_groups ( GF_DashClient dash,
const u32 groups_idx,
u32  nb_groups 
)

only enables the given groups - this shall be set before calling gf_dash_open. If NULL, no groups will be disabled

Parameters
dashthe target dash client
groups_idxlist of 0-based index of the target groups to enable,
nb_groupsnumber of group indexes in list

◆ gf_dash_split_adaptation_sets()

void gf_dash_split_adaptation_sets ( GF_DashClient dash)

split all adatation sets so that they contain only one representation (quality)

Parameters
dashthe target dash client

◆ gf_dash_set_low_latency_mode()

void gf_dash_set_low_latency_mode ( GF_DashClient dash,
GF_DASHLowLatencyMode  low_lat_mode 
)

allow early segment fetch in low latency mode

Parameters
dashthe target dash client
low_lat_modelow latency mode

◆ gf_dash_set_user_buffer()

void gf_dash_set_user_buffer ( GF_DashClient dash,
u32  buffer_time_ms 
)

indicates typical buffering used by the user app before playback starts. This allows fetching data earlier in live mode, if the timeshiftbuffer allows for it

Parameters
dashthe target dash client
buffer_time_mstypical playout buffer in milliseconds

◆ gf_dash_set_switching_probe_count()

void gf_dash_set_switching_probe_count ( GF_DashClient dash,
u32  switch_probe_count 
)

indicates the number of segments to wait before switching up bandwidth. The default value is 1 (ie stay in current bandwidth or one more segment before switching up, event if download rate is enough). Setting this to 0 means the switch will happen instantly, but this is more prone to quality changes due to network variations

Parameters
dashthe target dash client
switch_probe_countthe number of probes before switching

◆ gf_dash_set_agressive_adaptation()

void gf_dash_set_agressive_adaptation ( GF_DashClient dash,
Bool  enable_agressive_switch 
)

enables agressive switching mode. If agressive switching is enabled, switching targets to the closest bandwidth fitting the available download rate. Otherwise, switching targets the lowest bitrate representation that is above the currently played (eg does not try to switch to max bandwidth). Default value is no.

Parameters
dashthe target dash client
enable_agressive_switchif GF_TRUE, enables agressive mode, otherwise disables it

◆ gf_dash_enable_single_range_llhls()

void gf_dash_enable_single_range_llhls ( GF_DashClient dash,
Bool  enable_single_range 
)

enables single-range requests for LL-HLS byterange, rather than issuing a request per PART. This assumes that:

  • each URI in the different parts is the SAME
  • byte ranges are contiguous in the URL

Errors will be thrown if these are not met on future parts and merging will be disabled, however the scheduled buggy segment will NOT be disarded

Parameters
dashthe target dash client
enable_single_rangeif GF_TRUE, enables single range, otherwise disables it

◆ gf_dash_set_auto_switch()

void gf_dash_set_auto_switch ( GF_DashClient dash,
s32  auto_switch_count,
Bool  auto_switch_loop 
)

enable auto-switch mode

Parameters
dashthe target dash cleint
auto_switch_countforces representation switching (quality up if positive, down if negative) every auto_switch_count segments, set to 0 to disable
auto_switch_loopif false (default when creating dasher), restart at lowest quality when higher quality is reached and vice-versa. If true, quality switches decreases then increase in loop

◆ gf_dash_enable_cross_as_switch()

void gf_dash_enable_cross_as_switch ( GF_DashClient dash,
GF_DASHCrossASMode  cross_as_mode 
)

enable switching across adaptation sets

When switching across adaptation sets is enabled and such sets are declared in the manifest, a single group will be declared for all sets in the switching set, and switching will be handled by the client.

Parameters
dashthe target dash cleint
cross_as_modeenable or disable

◆ gf_dash_get_period_start()

u64 gf_dash_get_period_start ( GF_DashClient dash)

returns active period start

Parameters
dashthe target dash client
Returns
period start in milliseconds

◆ gf_dash_get_period_duration()

u64 gf_dash_get_period_duration ( GF_DashClient dash)

gets active period duration

Parameters
dashthe target dash client
Returns
active period duration in milliseconds

◆ gf_dash_group_get_num_qualities()

u32 gf_dash_group_get_num_qualities ( GF_DashClient dash,
u32  group_idx 
)

gets number of quality available for a group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
number of quality available

◆ gf_dash_group_get_num_components()

u32 gf_dash_group_get_num_components ( GF_DashClient dash,
u32  group_idx 
)

gets the number of components in a group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
number of components

◆ gf_dash_disable_speed_adaptation()

void gf_dash_disable_speed_adaptation ( GF_DashClient dash,
Bool  disable 
)

disable speed adaptation

Parameters
dashthe target dash client
disableif GF_TRUE? speed adaptation is disabled, otherwise it is enabled

◆ gf_dash_group_get_quality_info()

GF_Err gf_dash_group_get_quality_info ( GF_DashClient dash,
u32  group_idx,
u32  quality_idx,
GF_DASHQualityInfo quality 
)

gets information on a given quality

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
quality_idxthe 0-based index of the quality
qualityfilled with information for the desired quality
Returns
error if any

◆ gf_dash_group_get_template()

char* gf_dash_group_get_template ( GF_DashClient dash,
u32  group_idx,
u32 segment_timeline_timescale,
const char **  init_url,
const char **  hls_variant 
)

gets segment template info used by group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
segment_timeline_timescaleset to segment timeline timescale, or to 0 if no segment timeline
init_urlset to initialization URL (template, timeline or base URL for VoD) as indicated in manifest (no resolution to base URL)
hls_variantset toHLS variant name or NULL
Returns
segment template, NULL if no templates used. Memory must be freed by caller

◆ gf_dash_get_automatic_switching()

Bool gf_dash_get_automatic_switching ( GF_DashClient dash)

checks automatic switching mode

Parameters
dashthe target dash client
Returns
GF_TRUE if automatic quality switching is enabled

◆ gf_dash_set_automatic_switching()

GF_Err gf_dash_set_automatic_switching ( GF_DashClient dash,
Bool  enable_switching 
)

sets automatic quality switching mode. If automatic switching is off, switching can only happen based on caller inputs

Parameters
dashthe target dash client
enable_switchingif GF_TRUE, automatic switching is enabled; otherwise it is disabled
Returns
error if any

◆ gf_dash_group_select_quality()

GF_Err gf_dash_group_select_quality ( GF_DashClient dash,
u32  group_idx,
const char *  ID,
u32  q_idx 
)

selects quality of a group, either by ID or by index if ID is null

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
IDthe ID of the desired quality
q_idxthe 0-based index of the desired quality
Returns
error if any

◆ gf_dash_group_get_active_quality()

s32 gf_dash_group_get_active_quality ( GF_DashClient dash,
u32  group_idx 
)

gets currently active quality of a group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
the current quality index for the given group

◆ gf_dash_override_ntp()

void gf_dash_override_ntp ( GF_DashClient dash,
u64  server_ntp 
)

forces NTP of the DASH client to be the given NTP

Parameters
dashthe target dash client
server_ntpNTP timestamp to set as server clock

◆ gf_dash_set_tile_adaptation_mode()

void gf_dash_set_tile_adaptation_mode ( GF_DashClient dash,
GF_DASHTileAdaptationMode  mode,
u32  tile_rate_decrease 
)

sets tile adaptation mode

Parameters
dashthe target dash client
modethe desired tile adaptation mode
tile_rate_decreasepercentage (0->100) of global bandwidth to use at each level (recursive rate decrease for all level). If 0% or 100%, automatic rate allocation among tiles is performed (default mode)

◆ gf_dash_disable_low_quality_tiles()

void gf_dash_disable_low_quality_tiles ( GF_DashClient dash,
Bool  disable_tiles 
)

consider tile with highest quality degradation hints (not visible ones or not gazed at) as lost, triggering a GF_URL_REMOVE upon gf_dash_group_get_next_segment_location calls. Mostly used to debug tiling adaptation

Parameters
dashthe target dash client
disable_tilesif GF_TRUE, tiles with highest quality degradation hints will not be played.

◆ gf_dash_get_tile_adaptation_mode()

GF_DASHTileAdaptationMode gf_dash_get_tile_adaptation_mode ( GF_DashClient dash)

gets current tile adaptation mode

Parameters
dashthe target dash client
Returns
tile adaptation mode

◆ gf_dash_group_get_srd_max_size_info()

Bool gf_dash_group_get_srd_max_size_info ( GF_DashClient dash,
u32  group_idx,
u32 max_width,
u32 max_height 
)

gets max width and height in pixels of the SRD (Spatial Relationship Descriptor) a given group belongs to, if any

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
max_widthset to the maximum width of the SRD of this group
max_heightset to the maximum height of the SRD of this group
Returns
GF_TRUE if the group has an SRD descriptor associated, GF_FALSE otherwise

◆ gf_dash_group_get_srd_info()

Bool gf_dash_group_get_srd_info ( GF_DashClient dash,
u32  group_idx,
u32 srd_id,
u32 srd_x,
u32 srd_y,
u32 srd_w,
u32 srd_h,
u32 srd_width,
u32 srd_height 
)

gets SRD info, in SRD coordinate, of the SRD this group belongs to, if any

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
srd_idset to the id of the SRD of this group
srd_xset to the horizontal coordinate of the SRD of this group
srd_yset to the vertical coordinate of the SRD of this group
srd_wset to the width of the SRD of this group
srd_hset to the height of the SRD of this group
srd_widthset to the reference width (usually max width) of the SRD of this group
srd_heightset to the reference height (usually max height) of the SRD of this group
Returns
GF_TRUE if the group has an SRD descriptor associated, GF_FALSE otherwise

◆ gf_dash_group_set_quality_degradation_hint()

GF_Err gf_dash_group_set_quality_degradation_hint ( GF_DashClient dash,
u32  group_idx,
u32  quality_degradation_hint 
)

sets quality hint for the given group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
quality_degradation_hintquality degradation from 0 (no degradation) to 100 (worse quality possible)
Returns
error if any

◆ gf_dash_group_set_visible_rect()

GF_Err gf_dash_group_set_visible_rect ( GF_DashClient dash,
u32  group_idx,
u32  min_x,
u32  max_x,
u32  min_y,
u32  max_y,
Bool  is_gaze 
)

sets visible rectangle of a video object, may be used for adaptation. If min_x==max_x==min_y=max_y==0, disable adaptation

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
min_xhorizontal coordinate of first visible column
max_xhorizontal coordinate of last visible column
min_yhorizontal coordinate of first visible row
max_yhorizontal coordinate of last visible row
is_gazeif set, {min_x, min_y} indicate the position of the gaze (and {max_x, max_y} are ignored)
Returns
error if any

◆ gf_dash_ignore_xlink()

void gf_dash_ignore_xlink ( GF_DashClient dash,
Bool  ignore_xlink 
)

Ignores xlink on periods if some adaptation sets are specified in the period with xlink

Parameters
dashthe target dash client
ignore_xlinkif GF_TRUE? xlinks will be ignored on periods containing both xlinks and adaptation sets

◆ gf_dash_all_groups_done()

Bool gf_dash_all_groups_done ( GF_DashClient dash)

checks if all groups are done

Parameters
dashthe target dash client
Returns
GF_TRUE if all active groups in period are done

◆ gf_dash_set_period_xlink_query_string()

void gf_dash_set_period_xlink_query_string ( GF_DashClient dash,
const char *  query_string 
)

sets a query string to append to xlink on periods

Parameters
dashthe target dash client
query_stringthe query string to append to xlinks on periods

◆ gf_dash_set_chaining_mode()

void gf_dash_set_chaining_mode ( GF_DashClient dash,
u32  chaining_mode 
)

sets MPD chaining mode

Parameters
dashthe target dash client
chaining_modeif 0, no chaining. If 1, chain at end. If 2 chain on error or at end

◆ gf_dash_set_algo()

void gf_dash_set_algo ( GF_DashClient dash,
GF_DASHAdaptationAlgorithm  algo 
)

sets dash adaptation algorithm. Cannot be called on an active session

Parameters
dashthe target dash client
algothe algorithm to use

◆ gf_dash_set_group_download_state()

void gf_dash_set_group_download_state ( GF_DashClient dash,
u32  group_idx,
u32  dep_rep_idx,
GF_Err  err 
)

sets group download status of the last downloaded segment for non threaded modes

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
dep_rep_idxthe 0-based index of the current dependent rep
errerror status of the download, GF_OK if no error

◆ gf_dash_group_store_stats()

void gf_dash_group_store_stats ( GF_DashClient dash,
u32  group_idx,
u32  dep_rep_idx,
u32  bytes_per_sec,
u64  file_size,
Bool  is_broadcast,
u64  us_since_start 
)

sets group download statistics of the last downloaded segment for non threaded modes

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
dep_rep_idxthe 0-based index of the dependent rep
bytes_per_sectransfer rates in bytes per seconds
file_sizesegment size in bytes
is_broadcastset to GF_TRUE if the file is received over a multicast/broadcast link such as eMBMS or ROUTE (i.e. file was pushed to cache)
us_since_starttime in microseconds since start of the download

◆ gf_dash_set_suggested_presentation_delay()

void gf_dash_set_suggested_presentation_delay ( GF_DashClient dash,
s32  spd 
)

Shifts the computed availabilityStartTime by offsetting (or resetting) the SuggestedPresentationDelay value parsed in the DASH manifest

Parameters
dashthe target dash client
spdavailabilityStartTime shift in milliseconds. Positive values shift the clock in the future, negative ones in the past, "-I" will force the SuggestedPresentationDelay value to zero

◆ gf_dash_set_mcast_ast_shift()

void gf_dash_set_mcast_ast_shift ( GF_DashClient dash,
s32  ast_shift 
)

sets availabilityStartTime shift for multicast (ROUTE, FLUTE). By default the multicast tune-in is done by matching the last received segment name to the segment template and deriving the UTC reference from that. The function allows shifting the computed value by a given amount.

Parameters
dashthe target dash client
ast_shiftclock shift in milliseconds of the multicast receiver tune-in. Positive values shift the clock in the future, negative ones in the past

◆ gf_dash_get_min_wait_ms()

u32 gf_dash_get_min_wait_ms ( GF_DashClient dash)

gets the minimum wait time before calling gf_dash_process again for unthreaded mode

Parameters
dashthe target dash client
Returns
minimum wait time in ms

◆ gf_dash_group_get_as_id()

s32 gf_dash_group_get_as_id ( GF_DashClient dash,
u32  group_idx 
)

gets the adaptation set ID of a given group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
the adaptation set ID, -1 if not set

◆ gf_dash_group_has_init_segment()

Bool gf_dash_group_has_init_segment ( GF_DashClient dash,
u32  group_idx 
)

check if the group has an init segment associated

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
Returns
GF_TRUE if init segment is present, GF_FALSE otherwise

◆ gf_dash_group_get_sar()

void gf_dash_group_get_sar ( GF_DashClient dash,
u32  group_idx,
GF_Fraction sar 
)

get sample aspect ratio for video group

Parameters
dashthe target dash client
group_idxthe 0-based index of the target group
sarfilled with representation SAR if any, set to 0 otherwise - may be NULL

◆ gf_dash_set_algo_custom()

void gf_dash_set_algo_custom ( GF_DashClient dash,
void *  udta,
gf_dash_rate_adaptation  algo_custom,
gf_dash_download_monitor  download_monitor_custom 
)

sets custom rate adaptation logic

Parameters
dashthe target dash client
udtauser data to pass back to callback functions
algo_customrate adaptation custom logic
download_monitor_customdownload monitor custom logic

Variable Documentation

◆ GF_DASH_MPD_MIME_TYPES

const char* const GF_DASH_MPD_MIME_TYPES[] = { "application/dash+xml", "video/vnd.3gpp.mpd", "audio/vnd.3gpp.mpd", "video/vnd.mpeg.dash.mpd", "audio/vnd.mpeg.dash.mpd", NULL }
static

All the possible Mime-types for MPD files

◆ GF_DASH_M3U8_MIME_TYPES

const char* const GF_DASH_M3U8_MIME_TYPES[] = { "video/x-mpegurl", "audio/x-mpegurl", "application/x-mpegURL", "application/vnd.apple.mpegURL", NULL}
static

All the possible Mime-types for M3U8 files

◆ GF_DASH_SMOOTH_MIME_TYPES

const char* const GF_DASH_SMOOTH_MIME_TYPES[] = { "application/vnd.ms-sstr+xml", NULL}
static

All the possible Mime-types for Smooth files