---
title: Player.useMedia
description: Hook to access the media object from within a Player.Provider
---

import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
import Demo from "@/components/docs/demos/Demo.astro";
import DocsLink from "@/components/docs/DocsLink.astro";
import FrameworkCase from "@/components/docs/FrameworkCase.astro";
import StyleCase from "@/components/docs/StyleCase.astro";
import BasicUsageDemoReact from "@/components/docs/demos/use-media/react/css/BasicUsage";
import basicUsageReactTsx from "@/components/docs/demos/use-media/react/css/BasicUsage.tsx?raw";
import basicUsageReactCss from "@/components/docs/demos/use-media/react/css/BasicUsage.css?raw";

`Player.useMedia` (from <DocsLink slug="reference/create-player">`createPlayer`</DocsLink>) returns the current `Media` object (or `null` if no media has been registered yet). `Media` is a runtime-agnostic playback interface — any instance that conforms to it, including an `HTMLVideoElement`, can be the media. It exposes capabilities like `play()` and event subscription rather than assuming a native element. It must be called within a `Player.Provider`. The media object becomes available after a `<Video>` or `<Audio>` component mounts inside the provider tree. To attach a custom media element instead of the built-in components, see <DocsLink slug="reference/use-media-attach">`useMediaAttach`</DocsLink>.

## Examples

### Basic Usage

<FrameworkCase frameworks={["react"]}>
  <StyleCase styles={["css"]}>
    <Demo
      files={[
        { title: "App.tsx", code: basicUsageReactTsx, lang: "tsx" },
        { title: "App.css", code: basicUsageReactCss, lang: "css" },
      ]}
    >
      <BasicUsageDemoReact client:idle />
    </Demo>
  </StyleCase>
</FrameworkCase>

<UtilReference util="useMedia" />
