<commit_before># Deprecated list

# Table of Contents

- [overview](#overview)
- [A note about the Subtitle and Language APIs](#notes)
  - [Why changing the name?](#notes-why)
  - [API change](#notes-api)
- [Deprecated methods](#meth)
  - [setVideoBufferSize (replaced/updated)](#meth-setVideoBufferSize)
  - [setAudioBufferSize (replaced/updated)](#meth-setAudioBufferSize)
  - [getVideoBufferSize (replaced/updated)](#meth-getVideoBufferSize)
  - [getAudioBufferSize (replaced/updated)](#meth-getAudioBufferSize)
  - [getStartTime (replaced/updated)](#meth-getStartTime)
  - [getEndTime (replaced/updated)](#meth-getEndTime)
  - [goToStart (replaced/updated)](#meth-goToStart)
  - [getImageTrack (replaced)](#meth-getImageTrack)
  - [getCurrentTime (replaced/updated)](#meth-getCurrentTime)
  - [seekTo(WallClockTime) (updated)](#meth-seekTo)
  - [getMetrics (removed)](#meth-getMetrics)
  - [getAverageBitrates (removed)](#meth-getAverageBitrates)
  - [asObservable (removed)](#meth-asObservable)
  - [getDebug (removed)](#meth-getDebug)
  - [showDebug (removed)](#meth-showDebug)
  - [hideDebug (removed)](#meth-hideDebug)
  - [toggleDebug (removed)](#meth-toggleDebug)
  - [getVideoMaxBitrate (renamed)](#meth-setVideoMaxBitrate)
  - [getAudioMaxBitrate (renamed)](#meth-setAudioMaxBitrate)
  - [setVideoMaxBitrate (renamed)](#meth-setVideoMaxBitrate)
  - [setAudioMaxBitrate (renamed)](#meth-setAudioMaxBitrate)
  - [setFullscreen(false) (replaced/updated)](#meth-setFullscreen)
  - [getErrorTypes (renamed)](#meth-static-error-types)
  - [getErrorCodes (renamed)](#meth-static-error-codes)
  - [getAvailableLanguages (replaced/updated)](#meth-getAvailableLanguages)
  - [getAvailableSubtitles (replaced/updated)](#meth-getAvailableSubtitles)
  - [getLanguage (replaced/updated)](#meth-getLanguage)
  - [getSubtitle (replaced/updated)](#meth-getSubtitle)
  - [isLanguageAvailable (replaced/updated)](#meth-isLanguageAvailable)
  - [isSubtitleAvailable (replaced/updated)](#meth-isSubtitleAvailable)
  - [setLanguage (replaced/updated)](#meth-setLanguage)
  - [setSubtitle (replaced/updated)](#meth-setSubtitle)
- [Deprecated parameters](#options)
  - [loadVideo parameter timeFragment (replaced/updated)](#options-timeFragment)
  - [constructor parameter initVideoBitrate (renamed)](#options-initVideoBitrate)
  - [constructor parameter initAudioBitrate (renamed)](#options-initAudioBitrate)
  - [constructor and loadVideo parameter defaultLanguage (renamed/updated)](#options-defaultLanguage)
  - [constructor and loadVideo parameter defaultSubtitle (renamed/updated)](#options-defaultSubtitle)
  - [loadVideo parameter images (renamed)](#options-images)
  - [loadVideo parameter subtitles (renamed)](#options-subtitles)
- [Deprecated events](#events)
    - [currentTimeChange (replaced/updated)](#events-currentTimeChange)
    - [progress (removed)](#events-progress)
    - [languageChange (renamed/updated)](#events-languageChange)
    - [subtitleChange (renamed/updated)](#events-subtitleChange)

# <a name="overview"></a>Overview

This document is written to list and explain current deprecated calls and suggest more stable alternatives.

Currently, a large part of the API is deprecated, this is due to several facts:
  - the project goes from a relatively "slow" phase to a faster paced one, with new features and improvements coming.
  - the support of audio description and closed captions could led to an API breaking change if left that way. The update concerns A LOT of APIs (8 methods, 4 parameters and 2 events)
  - the upcoming ABR refacto will need to remove some APIs (getMetrics and getAverageBitrates)
  - new APIs had to be added.
  - the API was not consistent.

I understand that replacing otherwise functional code is not "fun", the current state is exceptional and will not be repeated to that extent.

Please note, that everything listed here still works until the next major release (v3.0.0).

## <a name="notes"></a>A note about the Subtitle and Language APIs

### <a name="notes-why"></a>Why changing the name?

All language-related API changed their name:
  - methods about the audio language now use the denomination "*AudioTrack" instead of "*Language"
  - methods about the subtitles language now use the denomination "*TextTrack" instead of "*Subtitle"

This is due to multiple reasons:
  - the word "language" is ambiguous here, and could apply to both audio and texts.
  - the API changed to add support for closed captions and audio description, and I do not want to break so many API calls without deprecating them first
  - as a user, we never know when to use "Subtitle" or "Subtitles" as both can be used as a singular form.
  - The word TextTrack for referring to subtitles is more idiomatic in the browser world than the word SubtitlesTrack. Subtitles are generally just translations, where TextTracks can be under several forms, most notably: "subtitles", "captions" and "descriptions".
  - TextTrack sounds good, refers to what we already call the "text" adaptation and is close to the AudioTrack name, so it leads to a more coherent and easy-to-remember API.

### <a name="notes-api"></a>API change

The new format for AudioTracks (previously Language) and TextTracks (previously Subtitle) changed, to support audio description (for the visually impaired), and closed captions (for the hard-of-hearing).

#### Format of a track

Basically, the new format for AudioTracks goes from:
```js
"fre"
```

to

```js
{
  id: "someId",
  language: "fre",
  audioDescription: false
}
```
(Of course, audioDescription is ``true`` when the track is... an audioDescription track).

And the new format for subtitles tracks goes from:
```js
"fre"
```
to:
```js
{
  id: "someId"
  language: "fre",
  closedCaption: false
}
```

#### Track getters

The format just defined in the previous chapter is what will be returned by the getters call:
  - getAudioTrack
  - getTextTrack

These two methods:
  - getAvailableTextTracks
  - getAvailableAudioTracks
Will have a supplementary property, ``active``, which is a boolean. If true, it means that the track is the one considered "active".

#### Track events

Same deal for the track events:
  - audioTrackChange
  - textTrackChange

They will both return the new format.

#### Track setters

When using the following methods:
  - setAudioTrack
  - setTextTrack

you now have to pass the __id__ part of a track.

For example:
```js
const tracks = player.getAvailableAudioTracks();

// setting the first track
player.setAudioTrack(tracks[0].id);
```

#### track options

For:
  - the ``defaultAudioTrack`` option in the constructor, ``loadVideo``
  - the ``defaultTextTrack`` option in the constructor, ``loadVideo``

You can either give:
  - a track object, without the id part.

    Such as:
    ```js
    {
      language: "fr",
      audioDescription: true
    }
    ```

    In which case, the first track respecting these conditions (here french audio with audioDescription) will be considered.

  - a string of the language you want.

    For example, for ``defaultAudioTrack``, ``"fre"`` is accepted and is inferred to be equal to ``{ language: "fre", audioDescription: false }``.


## <a name="meth"></a>Deprecated methods

### <a name="meth-setVideoBufferSize"></a>setVideoBufferSize

``setVideoBufferSize`` will be removed from the API. Its role can eventually be replaced by the new ``setWantedBufferAhaead`` API which will set the buffering goal (buffer size).

The only difference being than this is not type-related (as in audio/video types) anymore.

#### Why?
<commit_msg>doc: fix typo in doc/deprecated<commit_after># Deprecated list

# Table of Contents

- [overview](#overview)
- [A note about the Subtitle and Language APIs](#notes)
  - [Why changing the name?](#notes-why)
  - [API change](#notes-api)
- [Deprecated methods](#meth)
  - [setVideoBufferSize (replaced/updated)](#meth-setVideoBufferSize)
  - [setAudioBufferSize (replaced/updated)](#meth-setAudioBufferSize)
  - [getVideoBufferSize (replaced/updated)](#meth-getVideoBufferSize)
  - [getAudioBufferSize (replaced/updated)](#meth-getAudioBufferSize)
  - [getStartTime (replaced/updated)](#meth-getStartTime)
  - [getEndTime (replaced/updated)](#meth-getEndTime)
  - [goToStart (replaced/updated)](#meth-goToStart)
  - [getImageTrack (replaced)](#meth-getImageTrack)
  - [getCurrentTime (replaced/updated)](#meth-getCurrentTime)
  - [seekTo(WallClockTime) (updated)](#meth-seekTo)
  - [getMetrics (removed)](#meth-getMetrics)
  - [getAverageBitrates (removed)](#meth-getAverageBitrates)
  - [asObservable (removed)](#meth-asObservable)
  - [getDebug (removed)](#meth-getDebug)
  - [showDebug (removed)](#meth-showDebug)
  - [hideDebug (removed)](#meth-hideDebug)
  - [toggleDebug (removed)](#meth-toggleDebug)
  - [getVideoMaxBitrate (renamed)](#meth-setVideoMaxBitrate)
  - [getAudioMaxBitrate (renamed)](#meth-setAudioMaxBitrate)
  - [setVideoMaxBitrate (renamed)](#meth-setVideoMaxBitrate)
  - [setAudioMaxBitrate (renamed)](#meth-setAudioMaxBitrate)
  - [setFullscreen(false) (replaced/updated)](#meth-setFullscreen)
  - [getErrorTypes (renamed)](#meth-static-error-types)
  - [getErrorCodes (renamed)](#meth-static-error-codes)
  - [getAvailableLanguages (replaced/updated)](#meth-getAvailableLanguages)
  - [getAvailableSubtitles (replaced/updated)](#meth-getAvailableSubtitles)
  - [getLanguage (replaced/updated)](#meth-getLanguage)
  - [getSubtitle (replaced/updated)](#meth-getSubtitle)
  - [isLanguageAvailable (replaced/updated)](#meth-isLanguageAvailable)
  - [isSubtitleAvailable (replaced/updated)](#meth-isSubtitleAvailable)
  - [setLanguage (replaced/updated)](#meth-setLanguage)
  - [setSubtitle (replaced/updated)](#meth-setSubtitle)
- [Deprecated parameters](#options)
  - [loadVideo parameter timeFragment (replaced/updated)](#options-timeFragment)
  - [constructor parameter initVideoBitrate (renamed)](#options-initVideoBitrate)
  - [constructor parameter initAudioBitrate (renamed)](#options-initAudioBitrate)
  - [constructor and loadVideo parameter defaultLanguage (renamed/updated)](#options-defaultLanguage)
  - [constructor and loadVideo parameter defaultSubtitle (renamed/updated)](#options-defaultSubtitle)
  - [loadVideo parameter images (renamed)](#options-images)
  - [loadVideo parameter subtitles (renamed)](#options-subtitles)
- [Deprecated events](#events)
    - [currentTimeChange (replaced/updated)](#events-currentTimeChange)
    - [progress (removed)](#events-progress)
    - [languageChange (renamed/updated)](#events-languageChange)
    - [subtitleChange (renamed/updated)](#events-subtitleChange)

# <a name="overview"></a>Overview

This document is written to list and explain current deprecated calls and suggest more stable alternatives.

Currently, a large part of the API is deprecated, this is due to several facts:
  - the project goes from a relatively "slow" phase to a faster paced one, with new features and improvements coming.
  - the support of audio description and closed captions could led to an API breaking change if left that way. The update concerns A LOT of APIs (8 methods, 4 parameters and 2 events)
  - the upcoming ABR refacto will need to remove some APIs (getMetrics and getAverageBitrates)
  - new APIs had to be added.
  - the API was not consistent.

I understand that replacing otherwise functional code is not "fun", the current state is exceptional and will not be repeated to that extent.

Please note, that everything listed here still works until the next major release (v3.0.0).

## <a name="notes"></a>A note about the Subtitle and Language APIs

### <a name="notes-why"></a>Why changing the name?

All language-related API changed their name:
  - methods about the audio language now use the denomination "*AudioTrack" instead of "*Language"
  - methods about the subtitles language now use the denomination "*TextTrack" instead of "*Subtitle"

This is due to multiple reasons:
  - the word "language" is ambiguous here, and could apply to both audio and texts.
  - the API changed to add support for closed captions and audio description, and I do not want to break so many API calls without deprecating them first
  - as a user, we never know when to use "Subtitle" or "Subtitles" as both can be used as a singular form.
  - The word TextTrack for referring to subtitles is more idiomatic in the browser world than the word SubtitlesTrack. Subtitles are generally just translations, where TextTracks can be under several forms, most notably: "subtitles", "captions" and "descriptions".
  - TextTrack sounds good, refers to what we already call the "text" adaptation and is close to the AudioTrack name, so it leads to a more coherent and easy-to-remember API.

### <a name="notes-api"></a>API change

The new format for AudioTracks (previously Language) and TextTracks (previously Subtitle) changed, to support audio description (for the visually impaired), and closed captions (for the hard-of-hearing).

#### Format of a track

Basically, the new format for AudioTracks goes from:
```js
"fre"
```

to

```js
{
  id: "someId",
  language: "fre",
  audioDescription: false
}
```
(Of course, audioDescription is ``true`` when the track is... an audioDescription track).

And the new format for subtitles tracks goes from:
```js
"fre"
```
to:
```js
{
  id: "someId"
  language: "fre",
  closedCaption: false
}
```

#### Track getters

The format just defined in the previous chapter is what will be returned by the getters call:
  - getAudioTrack
  - getTextTrack

These two methods:
  - getAvailableTextTracks
  - getAvailableAudioTracks
Will have a supplementary property, ``active``, which is a boolean. If true, it means that the track is the one considered "active".

#### Track events

Same deal for the track events:
  - audioTrackChange
  - textTrackChange

They will both return the new format.

#### Track setters

When using the following methods:
  - setAudioTrack
  - setTextTrack

you now have to pass the __id__ part of a track.

For example:
```js
const tracks = player.getAvailableAudioTracks();

// setting the first track
player.setAudioTrack(tracks[0].id);
```

#### track options

For:
  - the ``defaultAudioTrack`` option in the constructor, ``loadVideo``
  - the ``defaultTextTrack`` option in the constructor, ``loadVideo``

You can either give:
  - a track object, without the id part.

    Such as:
    ```js
    {
      language: "fr",
      audioDescription: true
    }
    ```

    In which case, the first track respecting these conditions (here french audio with audioDescription) will be considered.

  - a string of the language you want.

    For example, for ``defaultAudioTrack``, ``"fre"`` is accepted and is inferred to be equal to ``{ language: "fre", audioDescription: false }``.


## <a name="meth"></a>Deprecated methods

### <a name="meth-setVideoBufferSize"></a>setVideoBufferSize

``setVideoBufferSize`` will be removed from the API. Its role can eventually be replaced by the new ``setWantedBufferAhead`` API which will set the buffering goal (buffer size).

The only difference being than this is not type-related (as in audio/video types) anymore.

#### Why?

{'fraction_non_alphanumeric': 0.11243813922797756, 'fraction_numerical': 0.0009237875288683603, 'mean_word_length': 4.82923076923077, 'pattern_counts': {'":': 0, '<': 27, '<?xml version=': 0, '>': 27, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4393726', 'n_tokens_mistral': 4636, 'n_tokens_neox': 4248, 'n_words': 1518}