Refactor useMediaInTimeline to remove mediaRef dependency and expose via Internals

[Copilot]

Overview

This PR refactors useMediaInTimeline to remove the mediaRef parameter, making it a cleaner, more reusable API that can now be used by @remotion/media components and custom media wrappers.

Problem

The original useMediaInTimeline hook required a mediaRef parameter, which was poor API design because:

• The media reference has nothing to do with showing media in the timeline
• It prevented the hook from being used with @remotion/media components that don't directly manage HTML media elements
• It mixed two separate concerns: timeline display and playback control

Solution

1. Created useMediaTag hook

Extracted the media playback control functionality into a separate internal hook (packages/core/src/use-media-tag.ts). This hook:

• Handles the part that actually needs mediaRef
• Registers playable media tags for imperative playback control
• Is exported via Internals for use by AudioForPreview and VideoForPreview

2. Refactored useMediaInTimeline

The hook now:

• Removes mediaRef parameter (no longer needed!)
• Removes onAutoPlayError, isPremounting, isPostmounting parameters (moved to useMediaTag)
• Focuses solely on timeline registration
• Is exported via Internals from remotion package for internal use

3. Updated existing components

Both AudioForPreview and VideoForPreview now use both hooks:

// Timeline display
useMediaInTimeline({
  volume,
  mediaVolume,
  src,
  mediaType: 'audio',
  playbackRate: 1,
  displayName: name ?? null,
  id: timelineId,
  stack: _remotionInternalStack,
  showInTimeline,
  premountDisplay: null,
  postmountDisplay: null,
});

// Playback control
useMediaTag({
  mediaRef: audioRef,
  id: timelineId,
  mediaType: 'audio',
  onAutoPlayError: null,
  isPremounting: Boolean(sequenceContext?.premounting),
  isPostmounting: Boolean(sequenceContext?.postmounting),
});

Usage Example

Internal code and @remotion/media components can use useMediaInTimeline via Internals to show custom media in the timeline without needing a media element reference:

import {Internals} from 'remotion';

export const CustomAudio: React.FC<{src: string}> = ({src}) => {
  Internals.useMediaInTimeline({
    volume: 1,
    mediaVolume: 1,
    src,
    mediaType: 'audio',
    playbackRate: 1,
    displayName: 'My Custom Audio',
    id: 'my-audio',
    stack: null,
    showInTimeline: true,
    premountDisplay: null,
    postmountDisplay: null,
  });

  // Your custom implementation here
  return <div>Custom audio player</div>;
};

Benefits

• ✅ Better API Design: Clear separation of concerns
• ✅ Reusability: Can now be used by @remotion/media and internal components
• ✅ Backward Compatibility: Existing components continue to work seamlessly
• ✅ Internal API: Available via Internals for internal use and @remotion/media package

Testing

• All 590 existing tests pass
• Updated test suite to reflect new API
• Verified with @remotion/media package builds

Closes #5704

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Use useMediaInTimeline or equivalent to show new media tags in the Remotion Studio timeline</issue_title>
<issue_description>1. Expose 'useMediaInTimeline'

2. Remove 'mediaRef' from the hook props, so it can be used both for old media components and the new ones.

As Jonny said:

The fact that it requires a mediaRef is actually bad design, it has nothing to do with showing the media in the timeline.

I would suggest that we remove the requirement for mediaRef, put it in a different hook, use that for the Audio/Video/OffthreadVideo tags

and then the useMediaInTimeline() tag can also work for @remotion/media</issue_description>

Comments on the Issue (you are @copilot in this section)

@JonnyBurger The fact that it requires a `mediaRef` is actually bad design, it has nothing to do with showing the media in the timeline.

I would suggest that we remove the requirement for mediaRef, put it in a different hook, use that for the Audio/Video/OffthreadVideo tags

and then the useMediaInTimeline() tag can also work for @remotion/media</comment_new>
<comment_new>@samohovets
@JonnyBurger true! I see 'mediaRef' is only used in one place there. Let's remove it. </comment_new>

Fixes #5704

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
bugs	Ready	Preview	Comment	Oct 6, 2025 10:06am
remotion	Ready	Preview	Comment	Oct 6, 2025 10:06am

[samohovets]

1. Do not expose it publicly. It should be exposed through "Internals.

2. No need for public doc.

[samohovets]

@copilot useMediaInTimeline is supposed to be the private API, no need for docs and public API. Expose it through Internals from "remotion"

[Copilot]

@copilot useMediaInTimeline is supposed to be the private API, no need for docs and public API. Expose it through Internals from "remotion"

Fixed in commit 2d64414. useMediaInTimeline is now:

• Exposed through Internals from "remotion"
• Removed from public API exports
• All documentation removed

1. Do not expose it publicly. It should be exposed through "Internals.

2. No need for public doc.

Done in commit 2d64414. useMediaInTimeline is now exposed through Internals and removed from public API. All public documentation has been removed.