/**
 * Take over the `<video>` elements a page already has.
 *
 * A page that was built around `<video>` — or around video.js, which is a
 * `<video>` with a script on top — should not have to be rewritten to gain a
 * demuxer. `upgradeVideoElements()` walks the document, puts a `<movi-player>`
 * where each `<video>` was, and carries its attributes and its children across:
 * the sources, the caption tracks, the poster, `data-setup`. What was declared
 * stays declared.
 *
 * The old element is kept, hidden, and wired to the new one, because a page's
 * JavaScript holds references to it: `video.play()`, `video.currentTime = 30`,
 * `video.addEventListener("ended", …)` all keep working, and keep meaning the
 * same thing, now that the player is what answers them. Existing code does not
 * know anything changed — which is the point.
 *
 * ```js
 * import { upgradeVideoElements } from "movi-player";
 *
 * upgradeVideoElements();                       // every <video> on the page
 * upgradeVideoElements("video.player");         // just these
 * upgradeVideoElements(document.querySelector("#hero"));
 *
 * const stop = upgradeVideoElements({ watch: true });   // …and future ones
 * ```
 *
 * A page opts a video out with `data-movi-ignore` — on the `<video>` itself or
 * on anything around it:
 *
 * ```html
 * <video data-movi-ignore src="clip.mp4" controls></video>
 * <section data-movi-ignore> …videos left alone… </section>
 * ```
 */
export interface UpgradeOptions {
    /** Where to look. Defaults to the whole document. */
    root?: ParentNode;
    /**
     * Keep watching for `<video>` elements added later — a route change, a lazy
     * component, an ad slot. The returned function stops watching.
     */
    watch?: boolean;
    /**
     * Attributes to put on every player this creates, for the things a `<video>`
     * has no way to ask for: `{ thumb: "", fallback: "native", sw: "auto" }`.
     */
    attributes?: Record<string, string>;
    /**
     * Forward the old element's API to the player, so code that still holds the
     * `<video>` keeps working. On by default; turn it off if the page is being
     * rewritten anyway and you would rather see it break loudly.
     */
    proxy?: boolean;
    /** Leave alone any `<video>` matching this selector. */
    skip?: string;
    /**
     * The last word on whether a particular `<video>` is taken.
     *
     * Everything else here asks what CAN be opened. This is for a caller that
     * also has to judge what SHOULD be — a page where videos are content rather
     * than a player, a grid of previews, a muted loop behind a headline. Called
     * with each candidate that has already passed the rest; return false to
     * leave it as it is.
     */
    filter?: (video: HTMLVideoElement) => boolean;
    /**
     * Is there media at the end of this element's links?
     *
     * An upgraded player reads the bytes itself, so a link that leads to
     * something else — a dead file, an expired signed URL, a paywall answering
     * with HTML — becomes a player with nothing to play, where the native
     * element would at least have shown the page's own error. From the DOM all
     * of those look like a perfectly good `<video src>`, so nothing here can
     * tell them apart.
     *
     * Whoever CAN is the caller. A browser extension has host permission and
     * can ask the server what is there; a page cannot, which is the same CORS
     * wall that makes the takeover necessary in the first place. So the
     * question is asked rather than answered: called with every URL this
     * element declares, absolute and in the order the page wrote them, return
     * false to leave the element alone.
     *
     * Not called at all when it is not supplied, which is the honest default —
     * an unanswerable question should not stop anything.
     */
    sourceCheck?: (urls: string[], video: HTMLVideoElement) => boolean;
    /**
     * Which sources may be taken over.
     *
     * "static" — the default — takes over a `<video>` that is playing a FILE at
     * a URL, and leaves every other one alone. The other ones are the sites that
     * feed the element themselves: YouTube, Netflix, anything on Media Source
     * Extensions, a camera on a MediaStream, anything under DRM. There is no
     * file behind those to open — the bytes arrive through JavaScript the page
     * is running — so taking the element away from them replaces a video that
     * works with a player that cannot possibly fetch anything, and breaks the
     * site. A video with no source yet is left alone for the same reason: that
     * is what a streaming site's element looks like a moment before its script
     * attaches to it.
     *
     * "any" upgrades whatever is there, for a caller who knows their page.
     */
    sources?: "static" | "any";
    /**
     * Leave the page's own layers over the video where they are.
     *
     * By default, anything the page painted over the old element and that sits
     * within the player's box — a big play button, a poster, a click-catcher, the
     * gradient a skin put under its controls — is hidden once the player is in
     * place, since it was drawn for a video that is no longer there and now
     * covers one that is. Set this for a page whose layers mean something on
     * their own.
     */
    keepOverlays?: boolean;
}
/** What an upgrade produced, for a caller that wants the pieces. */
export interface UpgradedVideo {
    /** The element that was there. Still in the DOM, hidden, and forwarding. */
    video: HTMLVideoElement;
    /** The player that replaced it. */
    player: HTMLElement;
}
/**
 * Is this element playing a file at a URL, rather than bytes a script is
 * feeding it? See UpgradeOptions.sources.
 */
export declare function hasStaticSource(video: HTMLVideoElement): boolean;
/**
 * Replace `<video>` elements with `<movi-player>`.
 *
 * @param target A selector, an element, a list of them, or the options object.
 * @param maybeOptions Options, when the first argument named what to upgrade.
 * @returns The upgrades performed. With `watch: true` the returned array also
 *   carries a `stop()` that ends the watching.
 */
export declare function upgradeVideoElements(target?: string | HTMLVideoElement | ArrayLike<HTMLVideoElement> | UpgradeOptions, maybeOptions?: UpgradeOptions): UpgradedVideo[] & {
    stop?: () => void;
};
/** The player that took over a given `<video>`, if one did. */
export declare function playerFor(video: HTMLVideoElement): HTMLElement | null;
//# sourceMappingURL=upgrade.d.ts.map