Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / src / web / html / html_media_element_5.lucb

#==============================================================================================
#
#   html_media_element_5 - HTML::HTMLMediaElement: tracks, the playback manager and the
#                          media data processing steps
#
#   DESCRIPTION:
#       Port of LibWeb/HTML/HTMLMediaElement.cpp lines 1520-1989: enabling an audio track and
#       selecting a video track, the external content source, updating the video frame and the
#       timeline, the audio / video track added steps, the metadata steps, setting up the
#       playback manager for remote and local resources, the media data processing steps, the
#       dedicated media source failure steps and forgetting the media-resource-specific tracks.
#
#       Playback is phase 4: LibMedia's PlaybackManager, DisplayingVideoSink and Track and the
#       DOM's AudioTrack(List) / VideoTrack(List) go to closure stubs.
#
#==============================================================================================

# mark: Tracks and video frames =================================================================

## Whether `tracks` has `track` (`Vector<Media::Track>::contains_slow`).
func html_media_element_tracks_contain(tracks: const ak.Vector[MediaTrack]*, track: MediaTrack) -> bool:
    for candidate in ak.vector_span_const(tracks):
        let candidate_track = candidate
        if media_track_eq(&candidate_track, &track):
            return true
    return false

## Ported from HTMLMediaElement.cpp:1520 Web::HTML::HTMLMediaElement::set_audio_track_enabled.
pub func html_media_element_set_audio_track_enabled(this: HtmlMediaElement*, audio_track: HtmlAudioTrack*?, enabled: bool):
    let playback_manager = this.m_playback_manager else trap("VERIFY: m_playback_manager")
    let track = html_audio_track_track_in_playback_manager(audio_track else trap("set_audio_track_enabled: null track"))

    let audio_tracks = media_playback_manager_audio_tracks(playback_manager)
    if not html_media_element_tracks_contain(&audio_tracks, track):
        return

    if enabled:
        media_playback_manager_enable_an_audio_track(playback_manager, track)
    else:
        media_playback_manager_disable_an_audio_track(playback_manager, track)

## Ported from HTMLMediaElement.cpp:1533 Web::HTML::HTMLMediaElement::ensure_external_content_source.
pub func html_media_element_ensure_external_content_source(this: HtmlMediaElement*) -> display_list.ExternalContentSource*:
    if this.m_external_content_source == none:
        this.m_external_content_source = display_list.external_content_source_create()
    return this.m_external_content_source else trap("unreachable")

## Ported from HTMLMediaElement.cpp:1540 Web::HTML::HTMLMediaElement::set_selected_video_track.
pub func html_media_element_set_selected_video_track(this: HtmlMediaElement*, video_track: HtmlVideoTrack*?):
    let playback_manager = this.m_playback_manager else trap("VERIFY: m_playback_manager")

    if let track = video_track:
        let video_tracks = media_playback_manager_video_tracks(playback_manager)
        if not html_media_element_tracks_contain(&video_tracks, html_video_track_track_in_playback_manager(track)):
            return

    if let external_content_source = this.m_external_content_source:
        display_list.external_content_source_clear(external_content_source)

    let previous_track = this.m_selected_video_track

    this.m_selected_video_track = video_track
    if let track = video_track:
        let sink = media_playback_manager_get_or_create_the_displaying_video_sink_for_track(playback_manager, html_video_track_track_in_playback_manager(track))
        this.m_selected_video_track_sink = sink
        let sink_update_result = media_displaying_video_sink_update(sink)
        if sink_update_result == MediaDisplayingVideoSinkUpdateResult.new_frame_available:
            display_list.external_content_source_update(html_media_element_ensure_external_content_source(this), media_displaying_video_sink_current_frame(sink))
            html_media_element_update_intrinsic_video_dimensions(this)
            dom_node_set_needs_repaint(this.dom_node())
        else:
            if let video_element = as_if_html_video_element(this):
                let video_data = media_track_video_data(html_video_track_track_in_playback_manager(track))
                html_video_element_set_intrinsic_video_dimensions(video_element, gfx.SizeOfU32(m_width = (u32)video_data.pixel_width, m_height = (u32)video_data.pixel_height))
    else:
        this.m_selected_video_track_sink = none

    if let previous = previous_track:
        media_playback_manager_remove_the_displaying_video_sink_for_track(playback_manager, html_video_track_track_in_playback_manager(previous))

## Ported from HTMLMediaElement.cpp:1572 Web::HTML::HTMLMediaElement::update_video_frame_and_timeline.
pub func html_media_element_update_video_frame_and_timeline(this: HtmlMediaElement*):
    let playback_manager = this.m_playback_manager else return

    if let sink = this.m_selected_video_track_sink:
        let sink_update_result = media_displaying_video_sink_update(sink)
        if sink_update_result == MediaDisplayingVideoSinkUpdateResult.new_frame_available:
            display_list.external_content_source_update(html_media_element_ensure_external_content_source(this), media_displaying_video_sink_current_frame(sink))
            html_media_element_update_intrinsic_video_dimensions(this)
            dom_node_set_needs_repaint(this.dom_node())

    # Wait for the seek to complete before updating the timestamp, otherwise we'll display the timestamp from
    # before the seek when the user lets go of the left mouse button.
    if html_media_element_seeking(this):
        return

    let current_time = media_playback_manager_current_time(playback_manager)
    let new_position = ak.duration_to_seconds_f64(&current_time)
    if new_position != this.m_current_playback_position:
        html_media_element_set_current_playback_position(this, new_position)

## Ported from HTMLMediaElement.cpp:1596 Web::HTML::HTMLMediaElement::on_audio_track_added.
pub func html_media_element_on_audio_track_added(this: HtmlMediaElement*, track: MediaTrack):
    let realm = html_media_element_realm(this)
    let audio_tracks = html_media_element_audio_tracks(this)
    let playback_manager = html_media_element_playback_manager(this)

    # 1. Create an AudioTrack object to represent the audio track.
    let audio_track = realm_create_html_audio_track(realm, realm, this, track)

    # 2. Update the media element's audioTracks attribute's AudioTrackList object with the new AudioTrack object.
    html_audio_track_list_add_track(audio_tracks, audio_track)

    # 3. Let enable be unknown.
    var enable = ak.TriState.unknown

    # 4. If either the media resource or the URL of the current media resource indicate a particular set of audio tracks to enable, or if
    #    the user agent has information that would facilitate the selection of specific audio tracks to improve the user's experience, then:
    #    if this audio track is one of the ones to enable, then set enable to true, otherwise, set enable to false.
    if let preferred_audio_track = media_playback_manager_preferred_audio_track(playback_manager):
        if media_track_eq(&track, &preferred_audio_track) and not this.m_has_enabled_preferred_audio_track:
            enable = ak.TriState.true_
            this.m_has_enabled_preferred_audio_track = true
        else:
            enable = ak.TriState.false_

    # 5. If enable is still unknown, then, if the media element does not yet have an enabled audio track, then set enable to true, otherwise,
    #    set enable to false.
    if enable == ak.TriState.unknown:
        enable = ak.TriState.true_ if not html_audio_track_list_has_enabled_track(audio_tracks) else ak.TriState.false_

    # 6. If enable is true, then enable this audio track, otherwise, do not enable this audio track.
    if enable == ak.TriState.true_:
        html_audio_track_set_enabled(audio_track, true)

    # 7. Fire an event named addtrack at this AudioTrackList object, using TrackEvent, with the track attribute initialized to the new AudioTrack object.
    var event_init = HtmlTrackEventInit()
    event_init.track = .audio_track(audio_track)

    let event = html_track_event_create(realm, html_event_names_addtrack, event_init)
    _ = dom_event_target_dispatch_event(audio_tracks.dom_event_target(), event.dom_event())

## Ported from HTMLMediaElement.cpp:1638 Web::HTML::HTMLMediaElement::on_video_track_added.
pub func html_media_element_on_video_track_added(this: HtmlMediaElement*, track: MediaTrack):
    let realm = html_media_element_realm(this)
    let video_tracks = html_media_element_video_tracks(this)
    let playback_manager = html_media_element_playback_manager(this)

    # 1. Create a VideoTrack object to represent the video track.
    let video_track = realm_create_html_video_track(realm, realm, this, track)

    # 2. Update the media element's videoTracks attribute's VideoTrackList object with the new VideoTrack object.
    html_video_track_list_add_track(video_tracks, video_track)

    # 3. Let enable be unknown.
    var enable = ak.TriState.unknown

    # 4. If either the media resource or the URL of the current media resource indicate a particular set of video tracks to enable, or if
    #    the user agent has information that would facilitate the selection of specific video tracks to improve the user's experience, then:
    #    if this video track is the first such video track, then set enable to true, otherwise, set enable to false.
    if let preferred_video_track = media_playback_manager_preferred_video_track(playback_manager):
        if media_track_eq(&track, &preferred_video_track) and not this.m_has_selected_preferred_video_track:
            enable = ak.TriState.true_
            this.m_has_selected_preferred_video_track = true
        else:
            enable = ak.TriState.false_

    # 5. If enable is still unknown, then, if the media element does not yet have a selected video track, then set enable to true, otherwise, set
    #    enable to false.
    if enable == ak.TriState.unknown:
        enable = ak.TriState.true_ if html_video_track_list_selected_index(video_tracks) == -1 else ak.TriState.false_

    # 6. If enable is true, then select this track and unselect any previously selected video tracks, otherwise, do not select this video track.
    #    If other tracks are unselected, then a change event will be fired.
    if enable == ak.TriState.true_:
        html_video_track_set_selected(video_track, true)

    # 7. Fire an event named addtrack at this VideoTrackList object, using TrackEvent, with the track attribute initialized to the new VideoTrack object.
    var event_init = HtmlTrackEventInit()
    event_init.track = .video_track(video_track)

    let event = html_track_event_create(realm, html_event_names_addtrack, event_init)
    _ = dom_event_target_dispatch_event(video_tracks.dom_event_target(), event.dom_event())

    dom_node_set_needs_repaint(this.dom_node())

## on_metadata_parsed's duration change callback: `GC::weak_callback(*this, [](auto& self, AK::Duration duration) { ... })`.
func html_media_element_on_duration_change(context: void*?, duration: ak.Duration):
    let captures = (HtmlMediaElementWeakFetchCallback*)(context else trap("on_duration_change: no captures"))
    let this = gc.weak_ptr(&captures.weak_self) else return
    html_media_element_set_duration_f64(this, ak.duration_to_seconds_f64(&duration))

## Ported from HTMLMediaElement.cpp:1683 Web::HTML::HTMLMediaElement::on_metadata_parsed.
pub func html_media_element_on_metadata_parsed(this: HtmlMediaElement*):
    let playback_manager = html_media_element_playback_manager(this)

    # FIXME: Move this to setup_playback_manager()
    html_media_element_update_volume(this)

    # AD-HOC: After selecting a track, we do not need the source element selector anymore.
    this.m_source_element_selector = none

    # FIXME: 1. Establish the media timeline for the purposes of the current playback position and the earliest possible position, based on the media data.
    # FIXME: 2. Update the timeline offset to the date and time that corresponds to the zero time in the media timeline established in the previous step,
    #           if any. If no explicit time and date is given by the media resource, the timeline offset must be set to Not-a-Number (NaN).

    # 3. Set the current playback position and the official playback position to the earliest possible position.
    this.m_current_playback_position = 0.0
    this.m_official_playback_position = 0.0

    # 4. Update the duration attribute with the time of the last frame of the resource, if known, on the media timeline established above. If it is
    #    not known (e.g. a stream that is in principle infinite), update the duration attribute to the value positive Infinity.
    # FIXME: Handle unbounded media resources.
    let duration = media_playback_manager_duration(playback_manager)
    html_media_element_set_duration_f64(this, ak.duration_to_seconds_f64(&duration))

    # NB: Register the duration change handler here so that we don't set the duration when the
    #     playback manager updates the duration after parsing.
    let weak_self = new HtmlMediaElementWeakFetchCallback(weak_self = gc.make_weak(this), fetch_generation = 0) else trap("out of memory")
    media_playback_manager_set_on_duration_change(playback_manager, ak.Function1[ak.Duration, unit](call = html_media_element_on_duration_change, context = weak_self))

    # 5. For video elements, set the videoWidth and videoHeight attributes, and queue a media element task given the media element to fire an event
    #    named resize at the media element.
    if let selected_video_track = this.m_selected_video_track:
        if let video_element = as_if_html_video_element(this):
            let video_data = media_track_video_data(html_video_track_track_in_playback_manager(selected_video_track))
            html_video_element_set_intrinsic_video_dimensions(video_element, gfx.SizeOfU32(m_width = (u32)video_data.pixel_width, m_height = (u32)video_data.pixel_height))

    # 6. Set the readyState attribute to HAVE_METADATA.
    html_media_element_set_ready_state(this, HtmlMediaElementReadyState.have_metadata)

    # 7. Let jumped be false.
    var jumped = false

    # 8. If the media element's default playback start position is greater than zero, then seek to that time, and let jumped be true.
    if this.m_default_playback_start_position > 0.0:
        html_media_element_seek_element(this, this.m_default_playback_start_position)
        jumped = true
    _ = jumped

    # 9. Set the media element's default playback start position to zero.
    this.m_default_playback_start_position = 0.0

    # FIXME: 10. Let the initial playback position be 0.
    # FIXME: 11. If either the media resource or the URL of the current media resource indicate a particular start time, then set the initial playback
    #            position to that time and, if jumped is still false, seek to that time.

    # 12. If there is no enabled audio track, then enable an audio track. This will cause a change event to be fired.
    let audio_tracks = html_media_element_audio_tracks(this)
    if not html_audio_track_list_has_enabled_track(audio_tracks):
        # m_audio_tracks->for_each_track([](auto& track) { track.set_enabled(true); return IterationDecision::Break; })
        var tracks = html_audio_track_list_tracks(audio_tracks)
        for track in ak.vector_span(&tracks):
            html_audio_track_set_enabled(track, true)
            break

    # 13. If there is no selected video track, then select a video track. This will cause a change event to be fired.
    let video_tracks = html_media_element_video_tracks(this)
    if html_video_track_list_selected_index(video_tracks) == -1:
        # m_video_tracks->for_each_track([](auto& track) { track.set_selected(true); return IterationDecision::Break; })
        var tracks = html_video_track_list_tracks(video_tracks)
        for track in ak.vector_span(&tracks):
            html_video_track_set_selected(track, true)
            break

    # AD-HOC: Now that we've enabled one of each available track type, the playback manager can be started. If this
    #         causes the playback manager to exit the initial state, the ready state should change.
    media_playback_manager_start(playback_manager)
    html_media_element_update_ready_state(this)

# mark: The playback manager ====================================================================

## The playback manager's callbacks hold the element weakly (`GC::weak_callback(*this, ...)`).
struct HtmlMediaElementPlaybackManagerCallback:
    var weak_self: gc.Weak[HtmlMediaElement]

    ## The weakly held element, if it is alive.
    func element() -> HtmlMediaElement*?:
        return gc.weak_ptr(&self.weak_self)

    ## set_up_playback_manager_for_remote's on_track_added.
    static func remote_track_added(context: void*?, track: const MediaTrack*):
        let captures = (HtmlMediaElementPlaybackManagerCallback*)(context else trap("on_track_added: no captures"))
        let this = captures.element() else return
        if media_track_type(track) == MediaTrackType.audio:
            html_media_element_on_audio_track_added(this, *track)
        else:
            html_media_element_on_video_track_added(this, *track)

    ## on_metadata_parsed: `self.on_metadata_parsed()`.
    static func metadata_parsed(context: void*?):
        let captures = (HtmlMediaElementPlaybackManagerCallback*)(context else trap("on_metadata_parsed: no captures"))
        let this = captures.element() else return
        html_media_element_on_metadata_parsed(this)

    ## on_playback_state_change: `self.on_playback_manager_state_change()`.
    static func playback_state_change(context: void*?):
        let captures = (HtmlMediaElementPlaybackManagerCallback*)(context else trap("on_playback_state_change: no captures"))
        let this = captures.element() else return
        html_media_element_on_playback_manager_state_change(this)

    ## on_unsupported_format_error: queue a task that cancels the fetch and runs the failure callback.
    static func unsupported_format_error(context: void*?, error_: MediaDecoderError):
        let captures = (HtmlMediaElementPlaybackManagerCallback*)(context else trap("on_unsupported_format_error: no captures"))
        let this = captures.element() else return
        # NB: Queue a task for this so that we don't destroy the PlaybackManager within one of its callbacks when we
        #     call forget_media_resource_specific_tracks().
        let task = new HtmlMediaElementDecoderErrorTask(weak_self = captures.weak_self, error_ = error_) else trap("out of memory")
        html_media_element_queue_a_media_element_task(this, ak.Function0[unit](call = HtmlMediaElementDecoderErrorTask.unsupported_format, context = task))

    ## on_error: queue a task that sets the decoder error.
    static func decoder_error(context: void*?, error_: MediaDecoderError):
        let captures = (HtmlMediaElementPlaybackManagerCallback*)(context else trap("on_error: no captures"))
        let this = captures.element() else return
        let task = new HtmlMediaElementDecoderErrorTask(weak_self = captures.weak_self, error_ = error_) else trap("out of memory")
        html_media_element_queue_a_media_element_task(this, ak.Function0[unit](call = HtmlMediaElementDecoderErrorTask.corrupted, context = task))

    ## set_up_playback_manager_for_local's on_track_added.
    static func local_track_added(context: void*?, track: const MediaTrack*):
        let captures = (HtmlMediaElementPlaybackManagerCallback*)(context else trap("on_track_added: no captures"))
        let this = captures.element() else return
        let playback_manager = html_media_element_playback_manager(this)
        if media_track_type(track) == MediaTrackType.audio:
            # self.m_audio_tracks->for_each_track([&](auto& element_track) { ... })
            var audio_tracks = html_audio_track_list_tracks(html_media_element_audio_tracks(this))
            for element_track in ak.vector_span(&audio_tracks):
                if not html_audio_track_enabled(element_track):
                    continue
                let element_media_track = html_audio_track_track_in_playback_manager(element_track)
                if media_track_eq(&element_media_track, track):
                    media_playback_manager_enable_an_audio_track(playback_manager, *track)
                    break
        elif media_track_type(track) == MediaTrackType.video:
            # self.m_video_tracks->for_each_track([&](auto& element_track) { ... })
            var video_tracks = html_video_track_list_tracks(html_media_element_video_tracks(this))
            for element_track in ak.vector_span(&video_tracks):
                if not html_video_track_selected(element_track):
                    continue
                let element_media_track = html_video_track_track_in_playback_manager(element_track)
                if media_track_eq(&element_media_track, track):
                    this.m_selected_video_track = element_track
                    this.m_selected_video_track_sink = media_playback_manager_get_or_create_the_displaying_video_sink_for_track(playback_manager, *track)
                    break

## The captures of the decoder error tasks: `[self = GC::Weak(self), error = move(error)]`.
struct HtmlMediaElementDecoderErrorTask:
    var weak_self: gc.Weak[HtmlMediaElement]
    var error_: MediaDecoderError

    ## If the media data can be fetched but is found by inspection to be in an unsupported format.
    static func unsupported_format(context: void*?):
        let captures = (HtmlMediaElementDecoderErrorTask*)(context else trap("unsupported format task: no captures"))
        let this = gc.weak_ptr(&captures.weak_self) else return
        if this.m_error != none:
            return

        # 1. The user agent should cancel the fetching process.
        let fetch_data = this.m_remote_fetch_data else trap("VERIFY: m_remote_fetch_data")
        let failure_callback = fetch_data.failure_callback
        html_media_element_cancel_the_fetching_process(this)

        # 2. Abort this subalgorithm, returning to the resource selection algorithm.
        ak.function1_call(&failure_callback, media_decoder_error_description(&captures.error_))

    ## If the media data is corrupted.
    static func corrupted(context: void*?):
        let captures = (HtmlMediaElementDecoderErrorTask*)(context else trap("corrupted task: no captures"))
        let this = gc.weak_ptr(&captures.weak_self) else return
        html_media_element_set_decoder_error(this, media_decoder_error_description(&captures.error_))

## `m_playback_manager = ...` and `m_playback_manager.clear()`: the OwnPtr's destructor runs the old
## manager's (PlaybackManager::~PlaybackManager, which revokes its weak link).
func html_media_element_set_playback_manager(this: HtmlMediaElement*, playback_manager: MediaPlaybackManager*?):
    let previous = this.m_playback_manager
    this.m_playback_manager = playback_manager
    if let old = previous:
        media_playback_manager_destruct(old)

## Ported from HTMLMediaElement.cpp:1760 Web::HTML::HTMLMediaElement::set_up_playback_manager_for_remote.
# https://html.spec.whatwg.org/multipage/media.html#media-data-processing-steps-list
pub func html_media_element_set_up_playback_manager_for_remote(this: HtmlMediaElement*):
    let playback_manager = media_playback_manager_create()
    html_media_element_set_playback_manager(this, playback_manager)
    let page = dom_document_page(html_media_element_document(this))
    media_playback_manager_set_audio_output_disabled(playback_manager, page_client_is_headless(page_client(page)))

    this.m_has_enabled_preferred_audio_track = false
    this.m_has_selected_preferred_video_track = false

    # NB: The spec is unclear on whether the following media resource track conditions should trigger multiple
    #     times on one media resource, but it is implied to be possible by the start of the "Media elements"
    #     section, where it says that a "media resource can have multiple audio and video tracks."
    #     https://html.spec.whatwg.org/multipage/media.html#media-elements
    #     Therefore, we enumerate all the available tracks into our VideoTrackList and AudioTrackList.

    let callback = new HtmlMediaElementPlaybackManagerCallback(weak_self = gc.make_weak(this)) else trap("out of memory")

    # -> If the media resource is found to have an audio track
    # -> If the media resource is found to have a video track
    media_playback_manager_set_on_track_added(playback_manager, ak.Function1[const MediaTrack*, unit](call = HtmlMediaElementPlaybackManagerCallback.remote_track_added, context = callback))

    # -> Once enough of the media data has been fetched to determine the duration of the media resource, its dimensions, and other metadata
    media_playback_manager_set_on_metadata_parsed(playback_manager, ak.Function0[unit](call = HtmlMediaElementPlaybackManagerCallback.metadata_parsed, context = callback))

    # -> If the media data can be fetched but is found by inspection to be in an unsupported format, or can otherwise not be rendered at all
    media_playback_manager_set_on_unsupported_format_error(playback_manager, ak.Function1[MediaDecoderError, unit](call = HtmlMediaElementPlaybackManagerCallback.unsupported_format_error, context = callback))

    # -> If the media data is corrupted
    media_playback_manager_set_on_error(playback_manager, ak.Function1[MediaDecoderError, unit](call = HtmlMediaElementPlaybackManagerCallback.decoder_error, context = callback))

    let fetch_data = this.m_remote_fetch_data else trap("set_up_playback_manager_for_remote: no remote fetch data")
    media_playback_manager_add_media_source(playback_manager, fetch_data.stream else trap("set_up_playback_manager_for_remote: no stream"))

    media_playback_manager_set_on_playback_state_change(playback_manager, ak.Function0[unit](call = HtmlMediaElementPlaybackManagerCallback.playback_state_change, context = callback))

## Ported from HTMLMediaElement.cpp:1825 Web::HTML::HTMLMediaElement::set_up_playback_manager_for_local.
# https://html.spec.whatwg.org/multipage/media.html#media-data-processing-steps-list
pub func html_media_element_set_up_playback_manager_for_local(this: HtmlMediaElement*):
    let playback_manager = media_playback_manager_create()
    html_media_element_set_playback_manager(this, playback_manager)
    let page = dom_document_page(html_media_element_document(this))
    media_playback_manager_set_audio_output_disabled(playback_manager, page_client_is_headless(page_client(page)))

    this.m_has_enabled_preferred_audio_track = false
    this.m_has_selected_preferred_video_track = false

    # NB: The spec is unclear on whether the following media resource track conditions should trigger multiple
    #     times on one media resource, but it is implied to be possible by the start of the "Media elements"
    #     section, where it says that a "media resource can have multiple audio and video tracks."
    #     https://html.spec.whatwg.org/multipage/media.html#media-elements
    #     Therefore, we enumerate all the available tracks into our VideoTrackList and AudioTrackList.

    let callback = new HtmlMediaElementPlaybackManagerCallback(weak_self = gc.make_weak(this)) else trap("out of memory")

    # AD-HOC: Enable the tracks in PlaybackManager if MediaSource already enabled them in the DOM.
    #         Note that we do not want to call on_(audio/video)_track_added() here, since the MSE spec takes care
    #         of setting up the tracks.
    media_playback_manager_set_on_track_added(playback_manager, ak.Function1[const MediaTrack*, unit](call = HtmlMediaElementPlaybackManagerCallback.local_track_added, context = callback))

    # -> Once enough of the media data has been fetched to determine the duration of the media resource, its dimensions, and other metadata
    media_playback_manager_set_on_metadata_parsed(playback_manager, ak.Function0[unit](call = HtmlMediaElementPlaybackManagerCallback.metadata_parsed, context = callback))

    # -> If the media data is corrupted
    media_playback_manager_set_on_error(playback_manager, ak.Function1[MediaDecoderError, unit](call = HtmlMediaElementPlaybackManagerCallback.decoder_error, context = callback))

    media_playback_manager_set_on_playback_state_change(playback_manager, ak.Function0[unit](call = HtmlMediaElementPlaybackManagerCallback.playback_state_change, context = callback))

# mark: The media data processing steps =========================================================

## process_media_data's task: `GC::weak_callback(*this, [](auto& self) { self.m_network_state = NetworkState::Loading; })`.
func html_media_element_set_network_state_loading(context: void*?):
    let captures = (HtmlMediaElementPlaybackManagerCallback*)(context else trap("network state task: no captures"))
    let this = captures.element() else return
    this.m_network_state = HtmlMediaElementNetworkState.loading

## Ported from HTMLMediaElement.cpp:1887 Web::HTML::HTMLMediaElement::process_media_data.
# https://html.spec.whatwg.org/multipage/media.html#media-data-processing-steps-list
pub func html_media_element_process_media_data(this: HtmlMediaElement*, fetching_status: HtmlMediaElementFetchingStatus):
    let realm = html_media_element_realm(this)

    # -> Once the entire media resource has been fetched (but potentially before any of it has been decoded)
    if fetching_status == HtmlMediaElementFetchingStatus.complete:
        # Fire an event named progress at the media element.
        html_media_element_fire_event(this, html_event_names_progress)

        # Set the networkState to NETWORK_IDLE and fire an event named suspend at the media element.
        this.m_network_state = HtmlMediaElementNetworkState.idle
        html_media_element_fire_event(this, html_event_names_suspend)
    elif fetching_status == HtmlMediaElementFetchingStatus.ongoing:
        # If the user agent ever discards any media data and then needs to resume the network activity to obtain it again, then it must queue a media
        # element task given the media element to set the networkState to NETWORK_LOADING.
        let callback = new HtmlMediaElementPlaybackManagerCallback(weak_self = gc.make_weak(this)) else trap("out of memory")
        html_media_element_queue_a_media_element_task(this, ak.Function0[unit](call = html_media_element_set_network_state_loading, context = callback))

    # -> If the connection is interrupted after some media data has been received, causing the user agent to give up trying
    #    to fetch the resource
    if fetching_status == HtmlMediaElementFetchingStatus.interrupted:
        # Fatal network errors that occur after the user agent has established whether the current media resource is usable
        # (i.e. once the media element's readyState attribute is no longer HAVE_NOTHING) must cause the user agent to
        # execute the following steps:
        if (u8)this.m_ready_state > (u8)HtmlMediaElementReadyState.have_nothing:
            assert(this.m_error == none)

            # 1. The user agent should cancel the fetching process.
            html_media_element_cancel_the_fetching_process(this)

            # 2. Set the error attribute to the result of creating a MediaError with MEDIA_ERR_NETWORK.
            this.m_error = realm_create_html_media_error(realm, realm, HtmlMediaErrorCode.network, ak.string_from_str("Connection interrupted"))

            # 3. Set the element's networkState attribute to the NETWORK_IDLE value.
            this.m_network_state = HtmlMediaElementNetworkState.idle

            # 4. Set the element's delaying-the-load-event flag to false. This stops delaying the load event.
            html_media_element_clear_delaying_the_load_event(this)

            # 5. Fire an event named error at the media element.
            html_media_element_fire_event(this, html_event_names_error)

            # 6. Abort the overall resource selection algorithm.
            # NB: Stopping the fetch stops the resource selection algorithm when the error is set.

    # FIXME: -> If the media data fetching process is aborted by the user
    # FIXME: -> If the media data can be fetched but has non-fatal errors or uses, in part, codecs that are unsupported, preventing the user agent from
    #           rendering the content completely correctly but not preventing playback altogether
    # FIXME: -> If the media resource is found to declare a media-resource-specific text track that the user agent supports

## Ported from HTMLMediaElement.cpp:1943 Web::HTML::HTMLMediaElement::handle_media_source_failure.
# https://html.spec.whatwg.org/multipage/media.html#dedicated-media-source-failure-steps
pub func html_media_element_handle_media_source_failure(this: HtmlMediaElement*, promises: const (JsPromiseCapability*)[], error_message: ak.String):
    let realm = html_media_element_realm(this)

    # 1. Set the error attribute to the result of creating a MediaError with MEDIA_ERR_SRC_NOT_SUPPORTED.
    this.m_error = realm_create_html_media_error(realm, realm, HtmlMediaErrorCode.src_not_supported, error_message)

    # 2. Forget the media element's media-resource-specific tracks.
    html_media_element_forget_media_resource_specific_tracks(this)

    # 3. Set the element's networkState attribute to the NETWORK_NO_SOURCE value.
    this.m_network_state = HtmlMediaElementNetworkState.no_source

    # 4. Set the element's show poster flag to true.
    html_media_element_set_show_poster(this, true)

    # 5. Fire an event named error at the media element.
    html_media_element_fire_event(this, html_event_names_error)

    # NB: If the error has been reset, that means we've entered load_element() within the error
    #     event handler. If that's the case, as part of the resource selection algorithm, these
    #     steps must abort.
    if this.m_error == none:
        return

    # 6. Reject pending play promises with promises and a "NotSupportedError" DOMException.
    html_media_element_reject_pending_play_promises_utf16_string(this, promises, ak.utf16_string_from_str("Media is not supported"), idl_not_supported_error_create)

    # 7. Set the element's delaying-the-load-event flag to false. This stops delaying the load event.
    html_media_element_clear_delaying_the_load_event(this)

## Ported from HTMLMediaElement.cpp:1976 Web::HTML::HTMLMediaElement::forget_media_resource_specific_tracks.
# https://html.spec.whatwg.org/multipage/media.html#forget-the-media-element's-media-resource-specific-tracks
pub func html_media_element_forget_media_resource_specific_tracks(this: HtmlMediaElement*):
    # When a media element is to forget the media element's media-resource-specific tracks, the user agent must remove from the media element's list
    # of text tracks all the media-resource-specific text tracks, then empty the media element's audioTracks attribute's AudioTrackList object, then
    # empty the media element's videoTracks attribute's VideoTrackList object. No events (in particular, no removetrack events) are fired as part of
    # this; the error and emptied events, fired by the algorithms that invoke this one, can be used instead.
    html_audio_track_list_remove_all_tracks(html_media_element_audio_tracks(this))
    html_video_track_list_remove_all_tracks(html_media_element_video_tracks(this))
    html_media_element_set_playback_manager(this, none)

    # NB: At this point, we no longer have any selected tracks to derive the video dimensions from.
    html_media_element_update_intrinsic_video_dimensions(this)