Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / src / web / html / html_media_element_6.lucb

#==============================================================================================
#
#   html_media_element_6 - HTML::HTMLMediaElement: ready states, playing, pausing, seeking,
#                          ending, time marching on, play promises and the controls
#
#   DESCRIPTION:
#       Port of LibWeb/HTML/HTMLMediaElement.cpp lines 1991-2864: the ready state steps and the
#       Media Source Extensions buffer monitoring, the playback manager's state changes, the
#       internal play and pause steps, seeking, notifying about playing, the poster flag,
#       paused, ended, the playback rates, blocked / stalled / potentially playing, autoplay
#       eligibility, the direction of playback, ended playback, reaching the end, timeupdate,
#       the time marches on steps, taking / resolving / rejecting pending play promises and
#       creating and destroying the media controls.
#
#==============================================================================================

# mark: Ready states ============================================================================

## set_ready_state's `ScopeGuard guard { [&] { ... } }`.
func html_media_element_set_ready_state_guard(this: HtmlMediaElement*):
    html_media_element_upon_has_ended_playback_possibly_changed(this)
    html_media_element_update_natural_dimensions(this)
    dom_node_set_needs_style_update(this.dom_node(), true)

## A ready state as its ordinal, for C++'s `<` / `>=` comparisons of the enum.
func html_media_element_ready_state_ordinal(ready_state: HtmlMediaElementReadyState) -> u8:
    return (u8)ready_state

## Ported from HTMLMediaElement.cpp:1991 Web::HTML::HTMLMediaElement::set_ready_state.
# https://html.spec.whatwg.org/multipage/media.html#ready-states:media-element-3
pub func html_media_element_set_ready_state(this: HtmlMediaElement*, ready_state: HtmlMediaElementReadyState):
    if this.m_ready_state == ready_state:
        return

    let old_ready_state = this.m_ready_state
    this.m_ready_state = ready_state

    defer html_media_element_set_ready_state_guard(this)

    let old_ordinal = html_media_element_ready_state_ordinal(old_ready_state)
    let new_ordinal = html_media_element_ready_state_ordinal(ready_state)

    # When the ready state of a media element whose networkState is not NETWORK_EMPTY changes, the user agent must
    # follow the steps given below:
    if this.m_network_state == HtmlMediaElementNetworkState.empty:
        return

    # 1. Apply the first applicable set of substeps from the following list:
    # -> If the previous ready state was HAVE_NOTHING, and the new ready state is HAVE_METADATA
    if old_ready_state == HtmlMediaElementReadyState.have_nothing and ready_state == HtmlMediaElementReadyState.have_metadata:
        # Queue a media element task given the media element to fire an event named loadedmetadata at the element.
        html_media_element_queue_firing_an_event(this, html_event_names_loadedmetadata)

        return

    # -> If the previous ready state was HAVE_METADATA and the new ready state is HAVE_CURRENT_DATA or greater
    if old_ready_state == HtmlMediaElementReadyState.have_metadata and new_ordinal >= (u8)HtmlMediaElementReadyState.have_current_data:
        # If this is the first time this occurs for this media element since the load() algorithm was last invoked, the user agent must queue a media
        # element task given the media element to fire an event named loadeddata at the element.
        if this.m_first_data_load_event_since_load_start:
            this.m_first_data_load_event_since_load_start = false

            html_media_element_queue_firing_an_event(this, html_event_names_loadeddata)

        # https://html.spec.whatwg.org/multipage/media.html#loading-the-media-resource:dom-media-readystate-4
        # Once the readyState attribute reaches HAVE_CURRENT_DATA, after the loadeddata event has been fired, 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)

        # If the new ready state is HAVE_FUTURE_DATA or HAVE_ENOUGH_DATA, then the relevant steps below must then be run also.
        if ready_state != HtmlMediaElementReadyState.have_future_data and ready_state != HtmlMediaElementReadyState.have_enough_data:
            return

    # -> If the previous ready state was HAVE_FUTURE_DATA or more, and the new ready state is HAVE_CURRENT_DATA or less
    if old_ordinal >= (u8)HtmlMediaElementReadyState.have_future_data and new_ordinal <= (u8)HtmlMediaElementReadyState.have_current_data:
        # FIXME: If the media element was potentially playing before its readyState attribute changed to a value lower than HAVE_FUTURE_DATA, and the element
        #        has not ended playback, and playback has not stopped due to errors, paused for user interaction, or paused for in-band content, the user agent
        #        must queue a media element task given the media element to fire an event named timeupdate at the element, and queue a media element task given
        #        the media element to fire an event named waiting at the element.
        return

    # -> If the previous ready state was HAVE_CURRENT_DATA or less, and the new ready state is HAVE_FUTURE_DATA
    if old_ordinal <= (u8)HtmlMediaElementReadyState.have_current_data and ready_state == HtmlMediaElementReadyState.have_future_data:
        # The user agent must queue a media element task given the media element to fire an event named canplay at the element.
        html_media_element_queue_firing_an_event(this, html_event_names_canplay)

        # If the element's paused attribute is false, the user agent must notify about playing for the element.
        if not html_media_element_paused(this):
            html_media_element_notify_about_playing(this)

        return

    # -> If the new ready state is HAVE_ENOUGH_DATA
    if ready_state == HtmlMediaElementReadyState.have_enough_data:
        # If the previous ready state was HAVE_CURRENT_DATA or less, the user agent must queue a media element task given the media element to fire an event
        # named canplay at the element, and, if the element's paused attribute is false, notify about playing for the element.
        if old_ordinal <= (u8)HtmlMediaElementReadyState.have_current_data:
            html_media_element_queue_firing_an_event(this, html_event_names_canplay)

            if not html_media_element_paused(this):
                html_media_element_notify_about_playing(this)

        # The user agent must queue a media element task given the media element to fire an event named canplaythrough at the element.
        html_media_element_queue_firing_an_event(this, html_event_names_canplaythrough)

        # If the element is not eligible for autoplay, then the user agent must abort these substeps.
        if not html_media_element_is_eligible_for_autoplay(this):
            return

        # The user agent may run the following substeps:
        # Set the paused attribute to false.
        html_media_element_set_paused(this, false)

        # If the element's show poster flag is true, set it to false and run the time marches on steps.
        if this.m_show_poster:
            html_media_element_set_show_poster(this, false)
            html_media_element_time_marches_on(this)

        # Queue a media element task given the element to fire an event named play at the element.
        html_media_element_queue_firing_an_event(this, html_event_names_play)

        # Notify about playing for the element.
        html_media_element_notify_about_playing(this)

        # FIXME: Alternatively, if the element is a video element, the user agent may start observing whether the element intersects the viewport. When the
        #        element starts intersecting the viewport, if the element is still eligible for autoplay, run the substeps above. Optionally, when the element
        #        stops intersecting the viewport, if the can autoplay flag is still true and the autoplay attribute is still specified, run the following substeps:
        #            Run the internal pause steps and set the can autoplay flag to true.
        #            Queue a media element task given the element to fire an event named pause at the element.
        return

## Ported from HTMLMediaElement.cpp:2118 Web::HTML::HTMLMediaElement::update_ready_state.
# https://w3c.github.io/media-source/#buffer-monitoring
pub func html_media_element_update_ready_state(this: HtmlMediaElement*):
    # AD-HOC: This method is invoked by our versions of the following Media Source Extensions algorithms to fulfill
    #         the necessary changes to the ready state.
    #          - https://w3c.github.io/media-source/#sourcebuffer-coded-frame-processing (steps 2-4)
    #          - https://w3c.github.io/media-source/#sourcebuffer-coded-frame-removal (step 3.5)
    #          - https://w3c.github.io/media-source/#sourcebuffer-init-segment-received (steps 8-9)
    #         We intentionally share this logic between local and remote playback, since it's the most specified
    #         algorithm regarding ready states during playback.

    let playback_manager = this.m_playback_manager else return

    # -> If the HTMLMediaElement's readyState attribute is HAVE_NOTHING:
    if this.m_ready_state == HtmlMediaElementReadyState.have_nothing:
        # 1. Abort these steps.
        return

    # -> If HTMLMediaElement's buffered does not contain a TimeRanges for the current playback position:
    let current_time = media_playback_manager_current_time(playback_manager)
    let ranges = media_playback_manager_buffered_time_ranges(playback_manager)
    let current_range = media_time_ranges_range_at_or_after(&ranges, current_time)
    let available_data = media_playback_manager_available_data(playback_manager)

    if available_data == MediaAvailableData.none_ or (available_data == MediaAvailableData.current and current_range == none):
        # 1. Set the HTMLMediaElement's readyState attribute to HAVE_METADATA.
        html_media_element_set_ready_state(this, HtmlMediaElementReadyState.have_metadata)
        # 2. Abort these steps.
        return

    # FIXME: It may be worth turning this into a heuristic based on the rate of change of the playback position and
    #        the buffered head.
    let have_enough_data_duration = ak.duration_from_seconds(5)

    let duration = media_playback_manager_duration(playback_manager)
    var current_range_end = ak.duration_zero()
    if let range = current_range:
        current_range_end = range.end
    # max(AK::Duration::zero(), current_range_end - current_time)
    var playable_duration = ak.duration_sub(&current_range_end, current_time)
    let zero = ak.duration_zero()
    if ak.duration_cmp(&zero, playable_duration) > 0:
        playable_duration = zero

    # -> If HTMLMediaElement's buffered contains a TimeRanges that includes the current playback position and
    #    enough data to ensure uninterrupted playback:
    if available_data == MediaAvailableData.future and (ak.duration_cmp(&playable_duration, have_enough_data_duration) >= 0 or ak.duration_cmp(&current_range_end, duration) >= 0):
        # 1. Set the HTMLMediaElement's readyState attribute to HAVE_ENOUGH_DATA.
        html_media_element_set_ready_state(this, HtmlMediaElementReadyState.have_enough_data)

        # 2. Playback may resume at this point if it was previously suspended by a transition to HAVE_CURRENT_DATA.
        # NB: Playback will have resumed due to PlaybackManager exiting buffering/seeking.

        # 3. Abort these steps.
        return

    # -> If HTMLMediaElement's buffered contains a TimeRanges that includes the current playback position and
    #    some time beyond the current playback position:
    if available_data == MediaAvailableData.future and ak.duration_cmp(&playable_duration, ak.duration_zero()) > 0:
        # 1. Set the HTMLMediaElement's readyState attribute to HAVE_FUTURE_DATA.
        html_media_element_set_ready_state(this, HtmlMediaElementReadyState.have_future_data)

        # 2. Playback may resume at this point if it was previously suspended by a transition to HAVE_CURRENT_DATA.
        # NB: Playback will have resumed due to PlaybackManager exiting buffering/seeking.

        # 3. Abort these steps.
        return

    # -> If HTMLMediaElement's buffered contains a TimeRanges that ends at the current playback position and
    #    does not have a range covering the time immediately after:
    # 1. Set the HTMLMediaElement's readyState attribute to HAVE_CURRENT_DATA.
    html_media_element_set_ready_state(this, HtmlMediaElementReadyState.have_current_data)

    # 2. Playback is suspended at this point since the media element doesn't have enough data to advance the media timeline.
    # NB: Playback is suspended by PlaybackManager being in buffering/seeking states.

    # 3. Abort these steps.
    return

## on_playback_manager_state_change's task: `GC::weak_callback(*this, [](auto& self) { ... })`.
func html_media_element_update_ready_state_task(context: void*?):
    let captures = (HtmlMediaElementPlaybackManagerCallback*)(context else trap("ready state task: no captures"))
    let this = captures.element() else return
    if (u8)this.m_ready_state >= (u8)HtmlMediaElementReadyState.have_metadata:
        html_media_element_update_ready_state(this)

## Ported from HTMLMediaElement.cpp:2201 Web::HTML::HTMLMediaElement::on_playback_manager_state_change.
pub func html_media_element_on_playback_manager_state_change(this: HtmlMediaElement*):
    let playback_manager = this.m_playback_manager else trap("VERIFY: m_playback_manager")
    let state = media_playback_manager_state(playback_manager)
    if html_media_element_seeking(this) and state != MediaPlaybackState.seeking:
        html_media_element_finish_seeking_element(this)

    # NB: Queue the readyState update as a task so that it will never run before the durationchange and loadedmetadata
    #     events are fired. This ensures that readyState has a deterministic value in those events.
    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_update_ready_state_task, context = callback))

# mark: Playing and pausing =====================================================================

## The captures of the tasks that hold taken play promises: `[this, promises = move(promises)]`.
struct HtmlMediaElementPlayPromisesTask:
    var this: HtmlMediaElement*
    var promises: ak.Vector[JsPromiseCapability*]

    ## play_element's step 4: resolve pending play promises with the result.
    static func resolve(context: void*?):
        let captures = (HtmlMediaElementPlayPromisesTask*)(context else trap("play promises task: no captures"))
        html_media_element_resolve_pending_play_promises(captures.this, ak.vector_span(&captures.promises))

    ## pause_element's step 3.
    static func pause(context: void*?):
        let captures = (HtmlMediaElementPlayPromisesTask*)(context else trap("play promises task: no captures"))
        let this = captures.this

        # 1. Fire an event named timeupdate at the element.
        html_media_element_dispatch_time_update_event(this)

        # 2. Fire an event named pause at the element.
        html_media_element_fire_event(this, html_event_names_pause)

        # 3. Reject pending play promises with promises and an "AbortError" DOMException.
        html_media_element_reject_pending_play_promises_utf16_string(this, ak.vector_span(&captures.promises), ak.utf16_string_from_str("Media playback was paused"), idl_abort_error_create)

    ## notify_about_playing's step 2.
    static func playing(context: void*?):
        let captures = (HtmlMediaElementPlayPromisesTask*)(context else trap("play promises task: no captures"))

        # 1. Fire an event named playing at the element.
        html_media_element_fire_event(captures.this, html_event_names_playing)

        # 2. Resolve pending play promises with promises.
        html_media_element_resolve_pending_play_promises(captures.this, ak.vector_span(&captures.promises))

## Ported from HTMLMediaElement.cpp:2217 Web::HTML::HTMLMediaElement::play_element.
# https://html.spec.whatwg.org/multipage/media.html#internal-play-steps
pub func html_media_element_play_element(this: HtmlMediaElement*):
    # 1. If the media element's networkState attribute has the value NETWORK_EMPTY, invoke the media element's resource
    #    selection algorithm.
    if this.m_network_state == HtmlMediaElementNetworkState.empty:
        html_media_element_select_resource(this)

    # 2. If the playback has ended and the direction of playback is forwards, seek to the earliest possible position
    #    of the media resource.
    if html_media_element_has_ended_playback(this) and html_media_element_direction_of_playback(this) == HtmlMediaElementPlaybackDirection.forwards:
        html_media_element_seek_element(this, 0.0)

    # 3. If the media element's paused attribute is true, then:
    if html_media_element_paused(this):
        # 1. Change the value of paused to false.
        html_media_element_set_paused(this, false)

        # 2. If the show poster flag is true, set the element's show poster flag to false and run the time marches on steps.
        if this.m_show_poster:
            html_media_element_set_show_poster(this, false)
            html_media_element_time_marches_on(this)

        # 3. Queue a media element task given the media element to fire an event named play at the element.
        html_media_element_queue_firing_an_event(this, html_event_names_play)

        # 4. If the media element's readyState attribute has the value HAVE_NOTHING, HAVE_METADATA, or HAVE_CURRENT_DATA,
        #    queue a media element task given the media element to fire an event named waiting at the element.
        if this.m_ready_state == HtmlMediaElementReadyState.have_nothing or this.m_ready_state == HtmlMediaElementReadyState.have_metadata or this.m_ready_state == HtmlMediaElementReadyState.have_current_data:
            html_media_element_queue_firing_an_event(this, html_event_names_waiting)
        #    Otherwise, the media element's readyState attribute has the value HAVE_FUTURE_DATA or HAVE_ENOUGH_DATA:
        #    notify about playing for the element.
        else:
            html_media_element_notify_about_playing(this)

            # AD-HOC: If the official playback position is at the end of the media data here, that means that we haven't
            #         run the reached the end of media playback steps. This can happen if we seeked to the end while paused
            #         and looping.
            #         See https://github.com/whatwg/html/issues/11774
            if this.m_official_playback_position == this.m_duration:
                html_media_element_reached_end_of_media_playback(this)

    # 4. Otherwise, if the media element's readyState attribute has the value HAVE_FUTURE_DATA or HAVE_ENOUGH_DATA, take
    #    pending play promises and queue a media element task given the media element to resolve pending play promises
    #    with the result.
    elif this.m_ready_state == HtmlMediaElementReadyState.have_future_data or this.m_ready_state == HtmlMediaElementReadyState.have_enough_data:
        let promises = html_media_element_take_pending_play_promises(this)

        let captures = new HtmlMediaElementPlayPromisesTask(this = this, promises = promises) else trap("out of memory")
        html_media_element_queue_a_media_element_task(this, ak.Function0[unit](call = HtmlMediaElementPlayPromisesTask.resolve, context = captures))

    # 5. Set the media element's can autoplay flag to false.
    this.m_can_autoplay = false

## Ported from HTMLMediaElement.cpp:2282 Web::HTML::HTMLMediaElement::pause_element.
# https://html.spec.whatwg.org/multipage/media.html#internal-pause-steps
pub func html_media_element_pause_element(this: HtmlMediaElement*):
    # 1. Set the media element's can autoplay flag to false.
    this.m_can_autoplay = false

    # 2. If the media element's paused attribute is false, run the following steps:
    if not html_media_element_paused(this):
        # 1. Change the value of paused to true.
        html_media_element_set_paused(this, true)

        # 2. Take pending play promises and let promises be the result.
        let promises = html_media_element_take_pending_play_promises(this)

        # 3. Queue a media element task given the media element and the following steps:
        let captures = new HtmlMediaElementPlayPromisesTask(this = this, promises = promises) else trap("out of memory")
        html_media_element_queue_a_media_element_task(this, ak.Function0[unit](call = HtmlMediaElementPlayPromisesTask.pause, context = captures))

        # 4. Set the official playback position to the current playback position.
        # AD-HOC: If the seeking attribute is set, we don't want to overwrite the official playback position, since that
        #         means it is temporarily set to the seeking target position instead of the current playback position.
        #         See: https://github.com/whatwg/html/issues/11773 and https://github.com/whatwg/html/pull/11792
        if not html_media_element_seeking(this):
            this.m_official_playback_position = this.m_current_playback_position

# mark: Seeking =================================================================================

## seek_element's tasks: `[this]() { finish_seeking_element(); }`.
func html_media_element_finish_seeking_element_task(context: void*?):
    html_media_element_finish_seeking_element((HtmlMediaElement*)(context else trap("finish seeking task: no element")))

## Ported from HTMLMediaElement.cpp:2319 Web::HTML::HTMLMediaElement::seek_element.
# https://html.spec.whatwg.org/multipage/media.html#dom-media-seek
pub func html_media_element_seek_element(this: HtmlMediaElement*, playback_position: f64, seek_mode: HtmlMediaSeekMode = HtmlMediaSeekMode.accurate):
    var new_playback_position = playback_position

    # 1. Set the media element's show poster flag to false.
    html_media_element_set_show_poster(this, false)

    # 2. If the media element's readyState is HAVE_NOTHING, return.
    if this.m_ready_state == HtmlMediaElementReadyState.have_nothing:
        return

    # 3. If the element's seeking IDL attribute is true, then another instance of this algorithm is already running.
    #    Abort that other instance of the algorithm without waiting for the step that it is running to complete.
    # NOTE: PlaybackManager will restart any ongoing seek, and only exit the seeking state once, so we don't need to
    #       check the seeking attribute here.

    # 4. Set the seeking IDL attribute to true.
    html_media_element_set_seeking(this, true)

    # 5. If the seek was in response to a DOM method call or setting of an IDL attribute, then continue the script. The
    #    remainder of these steps must be run in parallel. With the exception of the steps marked with ⌛, they could be
    #    aborted at any time by another instance of this algorithm being invoked.
    # NOTE: We implement the async nature of seeking through PlaybackManager, and the steps here are implemented as options
    #       that define how PlaybackManager's seeking behaves.

    # 6. If the new playback position is later than the end of the media resource, then let it be the end of the media resource instead.
    # AK::min(playback_position, m_duration): `b < a ? b : a`.
    if this.m_duration < new_playback_position:
        new_playback_position = this.m_duration

    # 7. If the new playback position is less than the earliest possible position, let it be that position instead.
    # AK::max(playback_position, 0): `a < b ? b : a`.
    if new_playback_position < 0.0:
        new_playback_position = 0.0

    # 8. If the (possibly now changed) new playback position is not in one of the ranges given in the seekable attribute,
    let time_ranges = html_media_element_seekable(this)
    if not html_time_ranges_in_range(time_ranges, new_playback_position):
        # then let it be the position in one of the ranges given in the seekable attribute that is the nearest to the new
        # playback position.

        # If there are no ranges given in the seekable attribute, then set the seeking IDL attribute to false and return.
        if html_time_ranges_length(time_ranges) == 0:
            html_media_element_set_seeking(this, false)
            return

        var nearest_point: f64 = 0.0
        var other_nearest_point: f64? = none
        var distance = math.infinity
        for i in 0..<html_time_ranges_length(time_ranges):
            let points: f64[2] = [html_time_ranges_start(time_ranges, (u32)i) else trap("MUST: TimeRanges::start"), html_time_ranges_end(time_ranges, (u32)i) else trap("MUST: TimeRanges::end")]
            for point in points:
                let point_distance = math.abs(new_playback_position - point)
                if point_distance < distance:
                    nearest_point = point
                    other_nearest_point = none
                    distance = point_distance
                elif point_distance == distance:
                    other_nearest_point = point

        # If two positions both satisfy that constraint (i.e. the new playback position is exactly in the middle between two ranges
        # in the seekable attribute), then use the position that is closest to the current playback position.
        if let other = other_nearest_point:
            let nearest_point_distance = math.abs(this.m_current_playback_position - nearest_point)
            let other_nearest_point_distance = math.abs(this.m_current_playback_position - other)
            if nearest_point_distance < other_nearest_point_distance:
                new_playback_position = nearest_point
            else:
                new_playback_position = other

    # AD-HOC: Ensure that currentTime returns the new playback position on the timeline immediately, as other
    #         browsers do.
    #         See https://github.com/whatwg/html/issues/11773
    this.m_official_playback_position = new_playback_position

    # 9. If the approximate-for-speed flag is set, adjust the new playback position to a value that will allow for playback to resume
    #    promptly. If new playback position before this step is before current playback position, then the adjusted new playback position
    #    must also be before the current playback position. Similarly, if the new playback position before this step is after current
    #    playback position, then the adjusted new playback position must also be after the current playback position.
    var manager_seek_mode = MediaSeekMode.accurate
    if seek_mode == HtmlMediaSeekMode.approximate_for_speed:
        if new_playback_position < html_media_element_current_playback_position(this):
            manager_seek_mode = MediaSeekMode.fast_before
        elif new_playback_position > html_media_element_current_playback_position(this):
            manager_seek_mode = MediaSeekMode.fast_after

    # 10. Queue a media element task given the media element to fire an event named seeking at the element.
    html_media_element_queue_firing_an_event(this, html_event_names_seeking)

    # 11. Set the current playback position to the new playback position.
    # NOTE: We set the playback position in finish_seeking_element(), once we've established the new playback position using
    #       the seek mode we've been provided.

    # 12. Wait until the user agent has established whether or not the media data for the new playback position is
    #     available, and, if it is, until it has decoded enough data to play back that position.
    if let playback_manager = this.m_playback_manager:
        var new_playback_position_as_duration = ak.duration_zero()
        if new_playback_position == this.m_duration:
            new_playback_position_as_duration = media_playback_manager_duration(playback_manager)
        else:
            new_playback_position_as_duration = ak.duration_from_seconds_f64(new_playback_position)
        media_playback_manager_seek(playback_manager, new_playback_position_as_duration, manager_seek_mode)

    # 13. Await a stable state. The synchronous section consists of all the remaining steps of this algorithm. (Steps in the
    #     synchronous section are marked with ⌛.)
    if this.m_playback_manager == none:
        # NB: The final steps are triggered by our playback manager exiting the seeking state its playing/paused state.
        # NB: Queue a media element task to ensure that that the seeking attribute is true while the seeking event fires.
        #     Awaiting a stable state seems to require a task to be queued anyway, and we use media element tasks to cancel
        #     ongoing operations when load_element() is called.
        #     See: https://github.com/whatwg/html/issues/2882#issuecomment-1108531815
        html_media_element_queue_a_media_element_task(this, ak.Function0[unit](call = html_media_element_finish_seeking_element_task, context = this))

## Ported from HTMLMediaElement.cpp:2442 Web::HTML::HTMLMediaElement::finish_seeking_element.
# https://html.spec.whatwg.org/multipage/media.html#dom-media-seek
pub func html_media_element_finish_seeking_element(this: HtmlMediaElement*):
    # 14. ⌛ Set the seeking IDL attribute to false.
    html_media_element_set_seeking(this, false)

    # NOTE: We deferred setting the current playback position until the async steps have completed.
    #       This fulfills step 11. This will also update the displayed frame to ensure that the user immediately
    #       sees the frame that we've seeked to.
    html_media_element_update_video_frame_and_timeline(this)

    # 15. ⌛ Run the time marches on steps.
    html_media_element_time_marches_on(this, HtmlMediaElementTimeMarchesOnReason.other)

    # 16. ⌛ Queue a media element task given the media element to fire an event named timeupdate at the element.
    html_media_element_queue_a_media_element_task(this, ak.Function0[unit](call = html_media_element_dispatch_time_update_event_task, context = this))

    # 17. ⌛ Queue a media element task given the media element to fire an event named seeked at the element.
    html_media_element_queue_firing_an_event(this, html_event_names_seeked)

## Ported from HTMLMediaElement.cpp:2467 Web::HTML::HTMLMediaElement::notify_about_playing.
# https://html.spec.whatwg.org/multipage/media.html#notify-about-playing
pub func html_media_element_notify_about_playing(this: HtmlMediaElement*):
    # 1. Take pending play promises and let promises be the result.
    let promises = html_media_element_take_pending_play_promises(this)

    # 2. Queue a media element task given the element and the following steps:
    let captures = new HtmlMediaElementPlayPromisesTask(this = this, promises = promises) else trap("out of memory")
    html_media_element_queue_a_media_element_task(this, ak.Function0[unit](call = HtmlMediaElementPlayPromisesTask.playing, context = captures))

    if let playback_manager = this.m_playback_manager:
        media_playback_manager_play(playback_manager)

    if html_audio_track_list_has_enabled_track(html_media_element_audio_tracks(this)):
        page_client_page_did_change_audio_play_state(page_client(dom_document_page(html_media_element_document(this))), HtmlAudioPlayState.playing)

## Ported from HTMLMediaElement.cpp:2488 Web::HTML::HTMLMediaElement::set_show_poster.
pub func html_media_element_set_show_poster(this: HtmlMediaElement*, show_poster: bool):
    if this.m_show_poster == show_poster:
        return

    this.m_show_poster = show_poster

    html_media_element_update_natural_dimensions(this)
    dom_node_set_needs_repaint(this.dom_node())

## Ported from HTMLMediaElement.cpp:2499 Web::HTML::HTMLMediaElement::set_paused.
pub func html_media_element_set_paused(this: HtmlMediaElement*, paused: bool):
    if this.m_paused == paused:
        return

    this.m_paused = paused

    if this.m_paused:
        if let playback_manager = this.m_playback_manager:
            media_playback_manager_pause(playback_manager)

        if html_audio_track_list_has_enabled_track(html_media_element_audio_tracks(this)):
            page_client_page_did_change_audio_play_state(page_client(dom_document_page(html_media_element_document(this))), HtmlAudioPlayState.paused)

    html_media_element_update_natural_dimensions(this)
    dom_node_set_needs_repaint(this.dom_node())
    dom_node_set_needs_style_update(this.dom_node(), true)

## Ported from HTMLMediaElement.cpp:2519 Web::HTML::HTMLMediaElement::set_ended.
pub func html_media_element_set_ended(this: HtmlMediaElement*, ended: bool):
    this.m_ended = ended

# mark: Playback rates and the media element's states ===========================================

## Ported from HTMLMediaElement.cpp:2525 Web::HTML::HTMLMediaElement::set_default_playback_rate.
# https://html.spec.whatwg.org/multipage/media.html#dom-media-defaultplaybackrate
pub func html_media_element_set_default_playback_rate(this: HtmlMediaElement*, new_value: f64):
    # When the defaultPlaybackRate or playbackRate attributes change value (either by being set by script or by being changed directly by the user agent, e.g. in response to user
    # control), the user agent must queue a media element task given the media element to fire an event named ratechange at the media element.
    if this.m_default_playback_rate != new_value:
        html_media_element_queue_firing_an_event(this, html_event_names_ratechange)

    # on setting the attribute must be set to the new value.
    this.m_default_playback_rate = new_value

## Ported from HTMLMediaElement.cpp:2540 Web::HTML::HTMLMediaElement::set_playback_rate.
# https://html.spec.whatwg.org/multipage/media.html#dom-media-playbackrate
pub func html_media_element_set_playback_rate(this: HtmlMediaElement*, new_value: f64) -> !:
    # on setting, the user agent must follow these steps:

    # 1. If the given value is not supported by the user agent, then throw a "NotSupportedError" DOMException.
    # FIXME: We need to support playback rates other than 1 for this to be even remotely useful.
    if new_value != 1.0:
        try idl_throw(.idl_dom_exception(idl_not_supported_error_create(html_media_element_realm(this), ak.utf16_string_from_str("Playback rates other than 1 are not supported."))))

    # When the defaultPlaybackRate or playbackRate attributes change value (either by being set by script or by being changed directly by the user agent, e.g. in response to user
    # control), the user agent must queue a media element task given the media element to fire an event named ratechange at the media element.
    if this.m_playback_rate != new_value:
        html_media_element_queue_firing_an_event(this, html_event_names_ratechange)

    # 2. Set playbackRate to the new value, and if the element is potentially playing, change the playback speed.
    this.m_playback_rate = new_value
    if html_media_element_potentially_playing(this):
        # FIXME: Do this once playback speeds other than 1 are supported.
        return

    return

## Ported from HTMLMediaElement.cpp:2567 Web::HTML::HTMLMediaElement::blocked.
# https://html.spec.whatwg.org/multipage/media.html#blocked-media-element
pub func html_media_element_blocked(this: HtmlMediaElement*) -> bool:
    # A media element is a blocked media element if its readyState attribute is in the HAVE_NOTHING state, the HAVE_METADATA
    # state, or the HAVE_CURRENT_DATA state, or if the element has paused for user interaction or paused for in-band content.
    match this.m_ready_state:
        .have_nothing, .have_metadata, .have_current_data:
            return true
        _:
            # FIXME: Implement "paused for user interaction" (namely "the user agent has reached a point in the media resource
            #        where the user has to make a selection for the resource to continue").
            # FIXME: Implement "paused for in-band content".
            return false

## Ported from HTMLMediaElement.cpp:2586 Web::HTML::HTMLMediaElement::stalled.
pub func html_media_element_stalled(this: HtmlMediaElement*) -> bool:
    # FIXME: Implement stall timeout. https://html.spec.whatwg.org/multipage/media.html#stall-timeout
    return false

## Ported from HTMLMediaElement.cpp:2593 Web::HTML::HTMLMediaElement::potentially_playing.
# https://html.spec.whatwg.org/multipage/media.html#potentially-playing
pub func html_media_element_potentially_playing(this: HtmlMediaElement*) -> bool:
    # A media element is said to be potentially playing when its paused attribute is false, the element has not ended
    # playback, playback has not stopped due to errors, and the element is not a blocked media element.
    # FIXME: Implement "stopped due to errors".
    return not html_media_element_paused(this) and not html_media_element_ended(this) and not html_media_element_blocked(this)

## Ported from HTMLMediaElement.cpp:2602 Web::HTML::HTMLMediaElement::is_eligible_for_autoplay.
# https://html.spec.whatwg.org/multipage/media.html#eligible-for-autoplay
pub func html_media_element_is_eligible_for_autoplay(this: HtmlMediaElement*) -> bool:
    let document = html_media_element_document(this)
    # A media element is said to be eligible for autoplay when all of the following conditions are met:
    #   - Its can autoplay flag is true.
    #   - Its paused attribute is true.
    #   - It has an autoplay attribute specified.
    #   - Its node document's active sandboxing flag set does not have the sandboxed automatic features browsing context flag set.
    #   - Its node document is allowed to use the "autoplay" feature.
    return this.m_can_autoplay and html_media_element_paused(this) and dom_element_has_attribute(this.dom_element(), html_attribute_names_autoplay) and not html_has_flag(dom_document_active_sandboxing_flag_set(document), HtmlSandboxingFlagSet.sandboxed_automatic_features) and dom_document_is_allowed_to_use_feature(document, DomPolicyControlledFeature.autoplay)

## Ported from HTMLMediaElement.cpp:2622 Web::HTML::HTMLMediaElement::direction_of_playback.
pub func html_media_element_direction_of_playback(this: HtmlMediaElement*) -> HtmlMediaElementPlaybackDirection:
    return HtmlMediaElementPlaybackDirection.forwards if this.m_playback_rate >= 0.0 else HtmlMediaElementPlaybackDirection.backwards

## Ported from HTMLMediaElement.cpp:2628 Web::HTML::HTMLMediaElement::has_ended_playback.
# https://html.spec.whatwg.org/multipage/media.html#ended-playback
pub func html_media_element_has_ended_playback(this: HtmlMediaElement*) -> bool:
    # A media element is said to have ended playback when:

    # The element's readyState attribute is HAVE_METADATA or greater, and
    if (u8)this.m_ready_state < (u8)HtmlMediaElementReadyState.have_metadata:
        return false

    # Either:
    #   - The current playback position is the end of the media resource, and
    #   - The direction of playback is forwards, and
    #   - The media element does not have a loop attribute specified.
    # AD-HOC: Use the value of the loop attribute from the last time we reached end of playback.
    #         Without this change, the ended attribute changes when enabling the loop attribute after
    #         playback has ended, and playback will not restart when playing the element.
    #         See https://github.com/whatwg/html/issues/11775
    if this.m_current_playback_position == this.m_duration and html_media_element_direction_of_playback(this) == HtmlMediaElementPlaybackDirection.forwards and not this.m_loop_was_specified_when_reaching_end_of_media_resource:
        return true

    # Or:
    #   - The current playback position is the earliest possible position, and
    #   - The direction of playback is backwards.
    if this.m_current_playback_position == 0.0 and html_media_element_direction_of_playback(this) == HtmlMediaElementPlaybackDirection.backwards:
        return true

    return false

## upon_has_ended_playback_possibly_changed's steps: `[&] { set_ended(has_ended_playback() && ...); }`.
func html_media_element_update_ended(context: void*?):
    let this = (HtmlMediaElement*)(context else trap("ended steps: no element"))
    # The ended attribute must return true if, the last time the event loop reached step 1, the media element had ended
    # playback and the direction of playback was forwards, and false otherwise.
    html_media_element_set_ended(this, html_media_element_has_ended_playback(this) and html_media_element_direction_of_playback(this) == HtmlMediaElementPlaybackDirection.forwards)

## Ported from HTMLMediaElement.cpp:2666 Web::HTML::HTMLMediaElement::upon_has_ended_playback_possibly_changed.
pub func html_media_element_upon_has_ended_playback_possibly_changed(this: HtmlMediaElement*):
    html_run_when_event_loop_reaches_step_1(gc.create_function0(gc.cell_heap(this.cell()), ak.Function0[unit](call = html_media_element_update_ended, context = this)))

## reached_end_of_media_playback's task: `[this]() mutable { ... }`.
func html_media_element_reached_end_task(context: void*?):
    let this = (HtmlMediaElement*)(context else trap("reached end task: no element"))

    # 1. Fire an event named timeupdate at the media element.
    html_media_element_dispatch_time_update_event(this)

    # 2. If the media element has ended playback, the direction of playback is forwards, and paused is false, then:
    if html_media_element_has_ended_playback(this) and html_media_element_direction_of_playback(this) == HtmlMediaElementPlaybackDirection.forwards and not html_media_element_paused(this):
        # 1. Set the paused attribute to true.
        html_media_element_set_paused(this, true)

        # 2. Fire an event named pause at the media element.
        html_media_element_fire_event(this, html_event_names_pause)

        # 3. Take pending play promises and reject pending play promises with the result and an "AbortError" DOMException.
        var promises = html_media_element_take_pending_play_promises(this)
        html_media_element_reject_pending_play_promises_utf16_string(this, ak.vector_span(&promises), ak.utf16_string_from_str("Media playback has ended"), idl_abort_error_create)

    # 3. Fire an event named ended at the media element.
    html_media_element_fire_event(this, html_event_names_ended)

## Ported from HTMLMediaElement.cpp:2676 Web::HTML::HTMLMediaElement::reached_end_of_media_playback.
# https://html.spec.whatwg.org/multipage/media.html#reaches-the-end
pub func html_media_element_reached_end_of_media_playback(this: HtmlMediaElement*):
    # 1. If the media element has a loop attribute specified,
    this.m_loop_was_specified_when_reaching_end_of_media_resource = dom_element_has_attribute(this.dom_element(), html_attribute_names_loop)
    if this.m_loop_was_specified_when_reaching_end_of_media_resource:
        # then seek to the earliest possible position of the media resource and return.
        # AD-HOC: We don't want to loop back to the start if we're paused.
        #         See https://github.com/whatwg/html/issues/11774
        if not html_media_element_paused(this):
            html_media_element_seek_element(this, 0.0)
        # FIXME: Tell PlaybackManager that we're looping to allow data providers to decode frames ahead when looping
        #        and remove any delay in displaying the first frame again.
        return

    # 2. As defined above, the ended IDL attribute starts returning true once the event loop returns to step 1.

    # 3. Queue a media element task given the media element and the following steps:
    html_media_element_queue_a_media_element_task(this, ak.Function0[unit](call = html_media_element_reached_end_task, context = this))

## dispatch_time_update_event's `ScopeGuard guard { [this] { m_running_time_update_event_handler = false; } }`.
func html_media_element_end_time_update_event_handler(this: HtmlMediaElement*):
    this.m_running_time_update_event_handler = false

## Ported from HTMLMediaElement.cpp:2716 Web::HTML::HTMLMediaElement::dispatch_time_update_event.
pub func html_media_element_dispatch_time_update_event(this: HtmlMediaElement*):
    defer html_media_element_end_time_update_event_handler(this)
    this.m_running_time_update_event_handler = true

    this.m_last_time_update_event_time = ak.monotonic_time_now()

    html_media_element_fire_event(this, html_event_names_timeupdate)

## Ported from HTMLMediaElement.cpp:2727 Web::HTML::HTMLMediaElement::time_marches_on.
# https://html.spec.whatwg.org/multipage/media.html#time-marches-on
pub func html_media_element_time_marches_on(this: HtmlMediaElement*, reason: HtmlMediaElementTimeMarchesOnReason = HtmlMediaElementTimeMarchesOnReason.normal_playback):
    # FIXME: 1. Let current cues be a list of cues, initialized to contain all the cues of all the hidden or showing text tracks
    #           of the media element (not the disabled ones) whose start times are less than or equal to the current playback
    #           position and whose end times are greater than the current playback position.
    # FIXME: 2. Let other cues be a list of cues, initialized to contain all the cues of hidden and showing text tracks of the
    #           media element that are not present in current cues.
    # FIXME: 3. Let last time be the current playback position at the time this algorithm was last run for this media element,
    #           if this is not the first time it has run.
    # FIXME: 4. If the current playback position has, since the last time this algorithm was run, only changed through its usual
    #           monotonic increase during normal playback, then let missed cues be the list of cues in other cues whose start times
    #           are greater than or equal to last time and whose end times are less than or equal to the current playback position.
    #           Otherwise, let missed cues be an empty list.
    # FIXME: 5. Remove all the cues in missed cues that are also in the media element's list of newly introduced cues, and then
    #           empty the element's list of newly introduced cues.

    # 6. If the time was reached through the usual monotonic increase of the current playback position during normal
    #    playback, and if the user agent has not fired a timeupdate event at the element in the past 15 to 250ms and is
    #    not still running event handlers for such an event, then the user agent must queue a media element task given
    #    the media element to fire an event named timeupdate at the element. (In the other cases, such as explicit seeks,
    #    relevant events get fired as part of the overall process of changing the current playback position.)
    if reason == HtmlMediaElementTimeMarchesOnReason.normal_playback and not this.m_running_time_update_event_handler:
        var dispatch_event = true

        if let last_time_update_event_time = this.m_last_time_update_event_time:
            let now = ak.monotonic_time_now()
            let time_since_last_event = ak.monotonic_time_sub_monotonic_time(&now, last_time_update_event_time)
            dispatch_event = ak.duration_to_milliseconds(&time_since_last_event) > 250

        if dispatch_event:
            html_media_element_queue_a_media_element_task(this, ak.Function0[unit](call = html_media_element_dispatch_time_update_event_task, context = this))

            # AD-HOC: Run the SourceBuffer monitoring algorithm to update readyState based on buffered data relative to
            #         the current playback position. This satisfies the periodic buffer monitoring in MSE:
            #         https://w3c.github.io/media-source/#buffer-monitoring
            html_media_element_update_ready_state(this)

    # FIXME: 7. If all of the cues in current cues have their text track cue active flag set, none of the cues in other cues have
    #           their text track cue active flag set, and missed cues is empty, then return.
    # FIXME: 8. If the time was reached through the usual monotonic increase of the current playback position during normal playback,
    #           and there are cues in other cues that have their text track cue pause-on-exit flag set and that either have their
    #           text track cue active flag set or are also in missed cues, then immediately pause the media element.
    # FIXME: 9. Let events be a list of tasks, initially empty. Each task in this list will be associated with a text track, a
    #           text track cue, and a time, which are used to sort the list before the tasks are queued.
    #
    #           Let affected tracks be a list of text tracks, initially empty.
    #
    #           When the steps below say to prepare an event named event for a text track cue target with a time time, the user
    #           agent must run these steps:
    #               1. Let track be the text track with which the text track cue target is associated.
    #               2. Create a task to fire an event named event at target.
    #               3. Add the newly created task to events, associated with the time time, the text track track, and the text
    #                  track cue target.
    #               4. Add track to affected tracks.
    # FIXME: 10. For each text track cue in missed cues, prepare an event named enter for the TextTrackCue object with the text
    #            track cue start time.
    # FIXME: 11. For each text track cue in other cues that either has its text track cue active flag set or is in missed cues,
    #            prepare an event named exit for the TextTrackCue object with the later of the text track cue end time and the
    #            text track cue start time.
    # FIXME: 12. For each text track cue in current cues that does not have its text track cue active flag set, prepare an event
    #            named enter for the TextTrackCue object with the text track cue start time.
    # FIXME: 13. Sort the tasks in events in ascending time order (tasks with earlier times first).
    #
    #            Further sort tasks in events that have the same time by the relative text track cue order of the text track cues
    #            associated with these tasks.
    #
    #            Finally, sort tasks in events that have the same time and same text track cue order by placing tasks that fire
    #            enter events before those that fire exit events.
    # FIXME: 14. Queue a media element task given the media element for each task in events, in list order.
    # FIXME: 15. Sort affected tracks in the same order as the text tracks appear in the media element's list of text tracks, and
    #            remove duplicates.
    # FIXME: 16. For each text track in affected tracks, in the list order, queue a media element task given the media element to
    #            fire an event named cuechange at the TextTrack object, and, if the text track has a corresponding track element,
    #            to then fire an event named cuechange at the track element as well.
    # FIXME: 17. Set the text track cue active flag of all the cues in the current cues, and unset the text track cue active flag
    #            of all the cues in the other cues.
    # FIXME: 18. Run the rules for updating the text track rendering of each of the text tracks in affected tracks that are showing,
    #            providing the text track's text track language as the fallback language if it is not the empty string. For example,
    #            for text tracks based on WebVTT, the rules for updating the display of WebVTT text tracks.
    return

# mark: Play promises and the controls ==========================================================

## Ported from HTMLMediaElement.cpp:2813 Web::HTML::HTMLMediaElement::take_pending_play_promises.
# https://html.spec.whatwg.org/multipage/media.html#take-pending-play-promises
pub func html_media_element_take_pending_play_promises(this: HtmlMediaElement*) -> ak.Vector[JsPromiseCapability*]:
    # 1. Let promises be an empty list of promises.
    # 2. Copy the media element's list of pending play promises to promises.
    # 3. Clear the media element's list of pending play promises.
    let promises = this.m_pending_play_promises
    this.m_pending_play_promises = ak.Vector[JsPromiseCapability*]()

    # 4. Return promises.
    return promises

## Ported from HTMLMediaElement.cpp:2826 Web::HTML::HTMLMediaElement::resolve_pending_play_promises.
# https://html.spec.whatwg.org/multipage/media.html#resolve-pending-play-promises
pub func html_media_element_resolve_pending_play_promises(this: HtmlMediaElement*, promises: const (JsPromiseCapability*)[]):
    let realm = html_media_element_realm(this)

    # AD-HOC: An execution context is required for Promise resolving hooks.
    var execution_context: HtmlTemporaryExecutionContext = ---
    html_temporary_execution_context_construct_realm(&execution_context, realm)
    defer html_temporary_execution_context_destruct(&execution_context)

    # To resolve pending play promises for a media element with a list of promises promises, the user agent
    # must resolve each promise in promises with undefined.
    for promise in promises:
        idl_resolve_promise(realm, promise, js_undefined())

## Ported from HTMLMediaElement.cpp:2840 Web::HTML::HTMLMediaElement::reject_pending_play_promises.
# https://html.spec.whatwg.org/multipage/media.html#reject-pending-play-promises
pub func html_media_element_reject_pending_play_promises_idl_dom_exception(this: HtmlMediaElement*, promises: const (JsPromiseCapability*)[], error_: IdlDomException*):
    let realm = html_media_element_realm(this)

    # AD-HOC: An execution context is required for Promise rejection hooks.
    var execution_context: HtmlTemporaryExecutionContext = ---
    html_temporary_execution_context_construct_realm(&execution_context, realm)
    defer html_temporary_execution_context_destruct(&execution_context)

    # To reject pending play promises for a media element with a list of promise promises and an exception name
    # error, the user agent must reject each promise in promises with error.
    for promise in promises:
        idl_reject_promise(realm, promise, bind_platform_object_wrapper(error_.bind_platform_object()))

## Ported from HTMLMediaElement.cpp:2853 Web::HTML::HTMLMediaElement::create_controls.
pub func html_media_element_create_controls(this: HtmlMediaElement*):
    if this.m_controls == none:
        # m_controls.emplace(*this): the controls live in a managed blob the element points to.
        let controls = new HtmlMediaControls() else trap("out of memory")
        this.m_controls = controls
        html_media_controls_construct(controls, this)

## Ported from HTMLMediaElement.cpp:2859 Web::HTML::HTMLMediaElement::destroy_controls.
pub func html_media_element_destroy_controls(this: HtmlMediaElement*):
    # m_controls.clear(): MediaControls' destructor runs.
    if let controls = this.m_controls:
        this.m_controls = none
        html_media_controls_destruct(controls)