remotion 4.0.110 → 4.0.112

package/README.md

@@ -44,7 +44,7 @@ Remotion is a framework for **creating videos programmatically using React.**
 If you already have Node.JS installed, type
 
 ```console
-npm init video
+npx create-video@latest
 ```
 
 to get started. Otherwise, read the [installation page](https://www.remotion.dev/docs/) in the documentation.

package/dist/cjs/Img.d.ts

@@ -1,6 +1,7 @@
 import React from 'react';
 export type ImgProps = Omit<React.DetailedHTMLProps<React.ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, 'src'> & {
     maxRetries?: number;
+    pauseWhenLoading?: boolean;
     src: string;
 };
 /**

package/dist/cjs/Img.js

@@ -6,12 +6,14 @@ const react_1 = require("react");
 const cancel_render_js_1 = require("./cancel-render.js");
 const delay_render_js_1 = require("./delay-render.js");
 const prefetch_js_1 = require("./prefetch.js");
+const use_buffer_state_js_1 = require("./use-buffer-state.js");
 function exponentialBackoff(errorCount) {
     return 1000 * 2 ** (errorCount - 1);
 }
-const ImgRefForwarding = ({ onError, maxRetries = 2, src, ...props }, ref) => {
+const ImgRefForwarding = ({ onError, maxRetries = 2, src, pauseWhenLoading, ...props }, ref) => {
     const imageRef = (0, react_1.useRef)(null);
     const errors = (0, react_1.useRef)({});
+    const { delayPlayback } = (0, use_buffer_state_js_1.useBufferState)();
     if (!src) {
         throw new Error('No "src" prop was passed to <Img>.');
     }
@@ -67,6 +69,9 @@ const ImgRefForwarding = ({ onError, maxRetries = 2, src, ...props }, ref) => {
                 return;
             }
             const newHandle = (0, delay_render_js_1.delayRender)('Loading <Img> with src=' + actualSrc);
+            const unblock = pauseWhenLoading
+                ? delayPlayback().unblock
+                : () => undefined;
             const { current } = imageRef;
             const onComplete = () => {
                 var _a, _b, _c, _d;
@@ -75,6 +80,7 @@ const ImgRefForwarding = ({ onError, maxRetries = 2, src, ...props }, ref) => {
                     // eslint-disable-next-line no-console
                     console.info(`Retry successful - ${(_d = imageRef.current) === null || _d === void 0 ? void 0 : _d.src} is now loaded`);
                 }
+                unblock();
                 (0, delay_render_js_1.continueRender)(newHandle);
             };
             const didLoad = () => {
@@ -89,9 +95,10 @@ const ImgRefForwarding = ({ onError, maxRetries = 2, src, ...props }, ref) => {
             // If tag gets unmounted, clear pending handles because image is not going to load
             return () => {
                 current === null || current === void 0 ? void 0 : current.removeEventListener('load', didLoad);
+                unblock();
                 (0, delay_render_js_1.continueRender)(newHandle);
             };
-        }, [actualSrc]);
+        }, [actualSrc, delayPlayback, pauseWhenLoading]);
     }
     return ((0, jsx_runtime_1.jsx)("img", { ...props, ref: imageRef, src: actualSrc, onError: didGetError }));
 };

package/dist/cjs/RemotionRoot.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RemotionRoot = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
+const buffering_js_1 = require("./buffering.js");
 const CompositionManager_js_1 = require("./CompositionManager.js");
 const delay_render_js_1 = require("./delay-render.js");
 const EditorProps_js_1 = require("./EditorProps.js");
@@ -69,6 +70,6 @@ const RemotionRoot = ({ children, numberOfAudioTags }) => {
             }
         }
     }, []);
-    return ((0, jsx_runtime_1.jsx)(nonce_js_1.NonceContext.Provider, { value: nonceContext, children: (0, jsx_runtime_1.jsx)(timeline_position_state_js_1.TimelineContext.Provider, { value: timelineContextValue, children: (0, jsx_runtime_1.jsx)(timeline_position_state_js_1.SetTimelineContext.Provider, { value: setTimelineContextValue, children: (0, jsx_runtime_1.jsx)(EditorProps_js_1.EditorPropsProvider, { children: (0, jsx_runtime_1.jsx)(prefetch_state_js_1.PrefetchProvider, { children: (0, jsx_runtime_1.jsx)(NativeLayers_js_1.NativeLayersProvider, { children: (0, jsx_runtime_1.jsx)(CompositionManager_js_1.CompositionManagerProvider, { numberOfAudioTags: numberOfAudioTags, children: (0, jsx_runtime_1.jsx)(duration_state_js_1.DurationsContextProvider, { children: children }) }) }) }) }) }) }) }));
+    return ((0, jsx_runtime_1.jsx)(nonce_js_1.NonceContext.Provider, { value: nonceContext, children: (0, jsx_runtime_1.jsx)(timeline_position_state_js_1.TimelineContext.Provider, { value: timelineContextValue, children: (0, jsx_runtime_1.jsx)(timeline_position_state_js_1.SetTimelineContext.Provider, { value: setTimelineContextValue, children: (0, jsx_runtime_1.jsx)(EditorProps_js_1.EditorPropsProvider, { children: (0, jsx_runtime_1.jsx)(prefetch_state_js_1.PrefetchProvider, { children: (0, jsx_runtime_1.jsx)(NativeLayers_js_1.NativeLayersProvider, { children: (0, jsx_runtime_1.jsx)(CompositionManager_js_1.CompositionManagerProvider, { numberOfAudioTags: numberOfAudioTags, children: (0, jsx_runtime_1.jsx)(duration_state_js_1.DurationsContextProvider, { children: (0, jsx_runtime_1.jsx)(buffering_js_1.BufferingProvider, { children: children }) }) }) }) }) }) }) }) }));
 };
 exports.RemotionRoot = RemotionRoot;

package/dist/cjs/audio/Audio.d.ts

@@ -13,6 +13,7 @@ export declare const Audio: React.ForwardRefExoticComponent<Omit<Omit<React.Deta
     _remotionInternalNeedsDurationCalculation?: boolean | undefined;
     _remotionInternalNativeLoopPassed?: boolean | undefined;
     toneFrequency?: number | undefined;
+    pauseWhenBuffering?: boolean | undefined;
 } & RemotionMainAudioProps & {
     /**
      * @deprecated For internal use only

package/dist/cjs/audio/Audio.js

@@ -16,13 +16,13 @@ const use_video_config_js_1 = require("../use-video-config.js");
 const validate_media_props_js_1 = require("../validate-media-props.js");
 const validate_start_from_props_js_1 = require("../validate-start-from-props.js");
 const duration_state_js_1 = require("../video/duration-state.js");
-const AudioForDevelopment_js_1 = require("./AudioForDevelopment.js");
+const AudioForPreview_js_1 = require("./AudioForPreview.js");
 const AudioForRendering_js_1 = require("./AudioForRendering.js");
 const shared_audio_tags_js_1 = require("./shared-audio-tags.js");
 const AudioRefForwardingFunction = (props, ref) => {
     var _a, _b, _c;
     const audioContext = (0, react_1.useContext)(shared_audio_tags_js_1.SharedAudioContext);
-    const { startFrom, endAt, name, stack, ...otherProps } = props;
+    const { startFrom, endAt, name, stack, pauseWhenBuffering, ...otherProps } = props;
     const { loop, ...propsOtherThanLoop } = props;
     const { fps } = (0, use_video_config_js_1.useVideoConfig)();
     const environment = (0, get_remotion_environment_js_1.getRemotionEnvironment)();
@@ -68,7 +68,9 @@ const AudioRefForwardingFunction = (props, ref) => {
     if (environment.isRendering) {
         return ((0, jsx_runtime_1.jsx)(AudioForRendering_js_1.AudioForRendering, { onDuration: onDuration, ...props, ref: ref, onError: onError, _remotionInternalNeedsDurationCalculation: Boolean(loop) }));
     }
-    return ((0, jsx_runtime_1.jsx)(AudioForDevelopment_js_1.AudioForDevelopment, { _remotionInternalNativeLoopPassed: (_c = props._remotionInternalNativeLoopPassed) !== null && _c !== void 0 ? _c : false, _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, shouldPreMountAudioTags: audioContext !== null && audioContext.numberOfAudioTags > 0, ...props, ref: ref, onError: onError, onDuration: onDuration, _remotionInternalNeedsDurationCalculation: Boolean(loop) }));
+    return ((0, jsx_runtime_1.jsx)(AudioForPreview_js_1.AudioForPreview, { _remotionInternalNativeLoopPassed: (_c = props._remotionInternalNativeLoopPassed) !== null && _c !== void 0 ? _c : false, _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, shouldPreMountAudioTags: audioContext !== null && audioContext.numberOfAudioTags > 0, ...props, ref: ref, onError: onError, onDuration: onDuration, 
+        // Proposal: Make this default to true in v5
+        pauseWhenBuffering: pauseWhenBuffering !== null && pauseWhenBuffering !== void 0 ? pauseWhenBuffering : false, _remotionInternalNeedsDurationCalculation: Boolean(loop) }));
 };
 /**
  * @description With this component, you can add audio to your video. All audio formats which are supported by Chromium are supported by the component.

package/dist/cjs/audio/AudioForRendering.d.ts

@@ -9,6 +9,7 @@ export declare const AudioForRendering: ForwardRefExoticComponent<Omit<React.Det
     _remotionInternalNeedsDurationCalculation?: boolean | undefined;
     _remotionInternalNativeLoopPassed?: boolean | undefined;
     toneFrequency?: number | undefined;
+    pauseWhenBuffering?: boolean | undefined;
 } & {
     onDuration: (src: string, durationInSeconds: number) => void;
 } & RefAttributes<HTMLAudioElement>>;

package/dist/cjs/audio/props.d.ts

@@ -13,4 +13,5 @@ export type RemotionAudioProps = Omit<React.DetailedHTMLProps<React.AudioHTMLAtt
     _remotionInternalNeedsDurationCalculation?: boolean;
     _remotionInternalNativeLoopPassed?: boolean;
     toneFrequency?: number;
+    pauseWhenBuffering?: boolean;
 };

package/dist/cjs/index.d.ts

@@ -93,7 +93,9 @@ export * from './spring/index.js';
 export { staticFile } from './static-file.js';
 export * from './Still.js';
 export type { PlayableMediaTag } from './timeline-position-state.js';
+export { useBufferState } from './use-buffer-state';
 export { useCurrentFrame } from './use-current-frame.js';
+export { CurrentScaleContextType, PreviewSize, PreviewSizeCtx, Translation, useCurrentScale, } from './use-current-scale';
 export * from './use-video-config.js';
 export * from './version.js';
 export * from './video-config.js';

package/dist/cjs/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Config = exports.Experimental = exports.watchStaticFile = exports.useCurrentFrame = exports.staticFile = exports.Series = exports.Sequence = exports.registerRoot = exports.prefetch = exports.random = exports.interpolate = exports.Loop = exports.interpolateColors = exports.Img = exports.getStaticFiles = exports.getRemotionEnvironment = exports.delayRender = exports.continueRender = exports.getInputProps = exports.Composition = exports.cancelRender = void 0;
+exports.Config = exports.Experimental = exports.watchStaticFile = exports.useCurrentScale = exports.useCurrentFrame = exports.useBufferState = exports.staticFile = exports.Series = exports.Sequence = exports.registerRoot = exports.prefetch = exports.random = exports.interpolate = exports.Loop = exports.interpolateColors = exports.Img = exports.getStaticFiles = exports.getRemotionEnvironment = exports.delayRender = exports.continueRender = exports.getInputProps = exports.Composition = exports.cancelRender = void 0;
 require("./asset-types.js");
 const Clipper_js_1 = require("./Clipper.js");
 const enable_sequence_stack_traces_js_1 = require("./enable-sequence-stack-traces.js");
@@ -64,8 +64,12 @@ __exportStar(require("./spring/index.js"), exports);
 var static_file_js_1 = require("./static-file.js");
 Object.defineProperty(exports, "staticFile", { enumerable: true, get: function () { return static_file_js_1.staticFile; } });
 __exportStar(require("./Still.js"), exports);
+var use_buffer_state_1 = require("./use-buffer-state");
+Object.defineProperty(exports, "useBufferState", { enumerable: true, get: function () { return use_buffer_state_1.useBufferState; } });
 var use_current_frame_js_1 = require("./use-current-frame.js");
 Object.defineProperty(exports, "useCurrentFrame", { enumerable: true, get: function () { return use_current_frame_js_1.useCurrentFrame; } });
+var use_current_scale_1 = require("./use-current-scale");
+Object.defineProperty(exports, "useCurrentScale", { enumerable: true, get: function () { return use_current_scale_1.useCurrentScale; } });
 __exportStar(require("./use-video-config.js"), exports);
 __exportStar(require("./version.js"), exports);
 __exportStar(require("./video-config.js"), exports);

package/dist/cjs/internals.d.ts

@@ -128,9 +128,37 @@ export declare const Internals: {
     readonly WATCH_REMOTION_STATIC_FILES: "remotion_staticFilesChanged";
     readonly addSequenceStackTraces: (component: unknown) => void;
     readonly useMediaStartsAt: () => number;
+    readonly BufferingProvider: import("react").FC<{
+        children: import("react").ReactNode;
+    }>;
+    readonly BufferingContextReact: import("react").Context<{
+        addBlock: (block: {
+            id: string;
+        }) => {
+            unblock: () => void;
+        };
+        listenForBuffering: (callback: () => void) => {
+            remove: () => void;
+        };
+        listenForResume: (callback: () => void) => {
+            remove: () => void;
+        };
+        buffering: import("react").MutableRefObject<boolean>;
+    } | null>;
     readonly enableSequenceStackTraces: () => void;
     readonly colorNames: {
         [key: string]: number;
     };
+    readonly CurrentScaleContext: import("react").Context<import("./use-current-scale.js").CurrentScaleContextType | null>;
+    readonly PreviewSizeContext: import("react").Context<import("./use-current-scale.js").PreviewSizeCtx>;
+    readonly calculateScale: ({ canvasSize, compositionHeight, compositionWidth, previewSize, }: {
+        previewSize: number | "auto";
+        compositionWidth: number;
+        compositionHeight: number;
+        canvasSize: {
+            width: number;
+            height: number;
+        };
+    }) => number;
 };
 export type { TComposition, TimelinePosition as Timeline, TCompMetadata, TSequence, TRenderAsset as TAsset, TimelineContextValue, SetTimelineContextValue, CompProps, CompositionManagerContext, MediaVolumeContextValue, SetMediaVolumeContextValue, RemotionEnvironment, SerializedJSONWithCustomFields, WatchRemotionStaticFilesPayload, };

package/dist/cjs/internals.js

@@ -26,6 +26,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Internals = void 0;
 const shared_audio_tags_js_1 = require("./audio/shared-audio-tags.js");
 const use_audio_frame_js_1 = require("./audio/use-audio-frame.js");
+const buffering_js_1 = require("./buffering.js");
 const CanUseRemotionHooks_js_1 = require("./CanUseRemotionHooks.js");
 const Composition_js_1 = require("./Composition.js");
 const CompositionManager_js_1 = require("./CompositionManager.js");
@@ -54,6 +55,7 @@ const setup_env_variables_js_1 = require("./setup-env-variables.js");
 const TimelinePosition = __importStar(require("./timeline-position-state.js"));
 const timeline_position_state_js_1 = require("./timeline-position-state.js");
 const truthy_js_1 = require("./truthy.js");
+const use_current_scale_js_1 = require("./use-current-scale.js");
 const use_lazy_component_js_1 = require("./use-lazy-component.js");
 const use_unsafe_video_config_js_1 = require("./use-unsafe-video-config.js");
 const use_video_js_1 = require("./use-video.js");
@@ -120,6 +122,11 @@ exports.Internals = {
     WATCH_REMOTION_STATIC_FILES: watch_static_file_js_1.WATCH_REMOTION_STATIC_FILES,
     addSequenceStackTraces: enable_sequence_stack_traces_js_1.addSequenceStackTraces,
     useMediaStartsAt: use_audio_frame_js_1.useMediaStartsAt,
+    BufferingProvider: buffering_js_1.BufferingProvider,
+    BufferingContextReact: buffering_js_1.BufferingContextReact,
     enableSequenceStackTraces: enable_sequence_stack_traces_js_1.enableSequenceStackTraces,
     colorNames: interpolate_colors_js_1.colorNames,
+    CurrentScaleContext: use_current_scale_js_1.CurrentScaleContext,
+    PreviewSizeContext: use_current_scale_js_1.PreviewSizeContext,
+    calculateScale: use_current_scale_js_1.calculateScale,
 };

package/dist/cjs/use-buffer-state.js

@@ -3,21 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useBufferState = void 0;
 const react_1 = require("react");
 const buffering_1 = require("./buffering");
-const CanUseRemotionHooks_1 = require("./CanUseRemotionHooks");
 const useBufferState = () => {
-    const canUseRemotionHooks = (0, react_1.useContext)(CanUseRemotionHooks_1.CanUseRemotionHooks);
-    if (!canUseRemotionHooks) {
-        if (typeof window !== 'undefined' && window.remotion_isPlayer) {
-            throw new Error(`useCurrentFrame can only be called inside a component that was passed to <Player>. See: https://www.remotion.dev/docs/player/examples`);
-        }
-        throw new Error(`useCurrentFrame() can only be called inside a component that was registered as a composition. See https://www.remotion.dev/docs/the-fundamentals#defining-compositions`);
-    }
     const buffer = (0, react_1.useContext)(buffering_1.BufferingContextReact);
-    if (!buffer) {
-        throw new Error('BufferingContextReact was unexpectedly not found. Most likely your Remotion versions are mismatching.');
-    }
     return (0, react_1.useMemo)(() => ({
         delayPlayback: () => {
+            if (!buffer) {
+                throw new Error('Tried to enable the buffering state, but a Remotion context was not found. This API can only be called in a component that was passed to the Remotion Player or a <Composition>. Or you might have experienced a version mismatch - run `npx remotion versions` and ensure all packages have the same version. This error is thrown by the buffer state https://remotion.dev/docs/player/buffer-state');
+            }
             const { unblock } = buffer.addBlock({
                 id: String(Math.random()),
             });

package/dist/cjs/use-current-scale.d.ts

@@ -0,0 +1,43 @@
+import React from 'react';
+export type CurrentScaleContextType = {
+    type: 'scale';
+    scale: number;
+} | {
+    type: 'canvas-size';
+    canvasSize: {
+        width: number;
+        height: number;
+    };
+};
+export declare const CurrentScaleContext: React.Context<CurrentScaleContextType | null>;
+type Options = {
+    dontThrowIfOutsideOfRemotion: boolean;
+};
+export type Translation = {
+    x: number;
+    y: number;
+};
+export type PreviewSize = {
+    size: number | 'auto';
+    translation: Translation;
+};
+export type PreviewSizeCtx = {
+    size: PreviewSize;
+    setSize: (cb: (oldSize: PreviewSize) => PreviewSize) => void;
+};
+export declare const PreviewSizeContext: React.Context<PreviewSizeCtx>;
+export declare const calculateScale: ({ canvasSize, compositionHeight, compositionWidth, previewSize, }: {
+    previewSize: PreviewSize['size'];
+    compositionWidth: number;
+    compositionHeight: number;
+    canvasSize: {
+        width: number;
+        height: number;
+    };
+}) => number;
+/**
+ * Gets the current scale of the container in which the component is being rendered.
+ * Only works in the Remotion Studio and in the Remotion Player.
+ */
+export declare const useCurrentScale: (options?: Options) => number;
+export {};

package/dist/cjs/use-current-scale.js

@@ -0,0 +1,70 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCurrentScale = exports.calculateScale = exports.PreviewSizeContext = exports.CurrentScaleContext = void 0;
+const react_1 = __importStar(require("react"));
+const use_unsafe_video_config_1 = require("./use-unsafe-video-config");
+exports.CurrentScaleContext = react_1.default.createContext(null);
+exports.PreviewSizeContext = (0, react_1.createContext)({
+    setSize: () => undefined,
+    size: { size: 'auto', translation: { x: 0, y: 0 } },
+});
+const calculateScale = ({ canvasSize, compositionHeight, compositionWidth, previewSize, }) => {
+    const heightRatio = canvasSize.height / compositionHeight;
+    const widthRatio = canvasSize.width / compositionWidth;
+    const ratio = Math.min(heightRatio, widthRatio);
+    return previewSize === 'auto' ? ratio : Number(previewSize);
+};
+exports.calculateScale = calculateScale;
+/**
+ * Gets the current scale of the container in which the component is being rendered.
+ * Only works in the Remotion Studio and in the Remotion Player.
+ */
+const useCurrentScale = (options) => {
+    const hasContext = react_1.default.useContext(exports.CurrentScaleContext);
+    const zoomContext = react_1.default.useContext(exports.PreviewSizeContext);
+    const config = (0, use_unsafe_video_config_1.useUnsafeVideoConfig)();
+    if (hasContext === null || config === null || zoomContext === null) {
+        if (options === null || options === void 0 ? void 0 : options.dontThrowIfOutsideOfRemotion) {
+            return 1;
+        }
+        throw new Error([
+            'useCurrentScale() was called outside of a Remotion context.',
+            'This hook can only be called in a component that is being rendered by Remotion.',
+            'If you want to this hook to return 1 outside of Remotion, pass {dontThrowIfOutsideOfRemotion: true} as an option.',
+            'If you think you called this hook in a Remotion component, make sure all versions of Remotion are aligned.',
+        ].join('\n'));
+    }
+    if (hasContext.type === 'scale') {
+        return hasContext.scale;
+    }
+    return (0, exports.calculateScale)({
+        canvasSize: hasContext.canvasSize,
+        compositionHeight: config.height,
+        compositionWidth: config.width,
+        previewSize: zoomContext.size.size,
+    });
+};
+exports.useCurrentScale = useCurrentScale;

package/dist/cjs/use-media-playback.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useMediaPlayback = exports.DEFAULT_ACCEPTABLE_TIMESHIFT = void 0;
 const react_1 = require("react");
 const use_audio_frame_js_1 = require("./audio/use-audio-frame.js");
+const buffering_js_1 = require("./buffering.js");
 const play_and_handle_not_allowed_error_js_1 = require("./play-and-handle-not-allowed-error.js");
 const timeline_position_state_js_1 = require("./timeline-position-state.js");
 const use_current_frame_js_1 = require("./use-current-frame.js");
@@ -27,6 +28,7 @@ const useMediaPlayback = ({ mediaRef, src, mediaType, playbackRate: localPlaybac
     const frame = (0, use_current_frame_js_1.useCurrentFrame)();
     const absoluteFrame = (0, timeline_position_state_js_1.useTimelinePosition)();
     const [playing] = (0, timeline_position_state_js_1.usePlayingState)();
+    const buffering = (0, react_1.useContext)(buffering_js_1.BufferingContextReact);
     const { fps } = (0, use_video_config_js_1.useVideoConfig)();
     const mediaStartsAt = (0, use_audio_frame_js_1.useMediaStartsAt)();
     const playbackRate = localPlaybackRate * globalPlaybackRate;
@@ -38,12 +40,13 @@ const useMediaPlayback = ({ mediaRef, src, mediaType, playbackRate: localPlaybac
         }
         return acceptableTimeshift;
     })();
+    const pausedOrBuffering = !playing || (buffering && buffering.buffering);
     (0, react_1.useEffect)(() => {
         var _a;
-        if (!playing) {
+        if (pausedOrBuffering) {
             (_a = mediaRef.current) === null || _a === void 0 ? void 0 : _a.pause();
         }
-    }, [mediaRef, mediaType, playing]);
+    }, [mediaRef, mediaType, pausedOrBuffering]);
     (0, react_1.useEffect)(() => {
         const tagName = mediaType === 'audio' ? '<Audio>' : '<Video>';
         if (!mediaRef.current) {
@@ -83,12 +86,14 @@ const useMediaPlayback = ({ mediaRef, src, mediaType, playbackRate: localPlaybac
         // Refer to the https://github.com/remotion-dev/video-buffering-example
         // which is fixed by only seeking conditionally.
         const makesSenseToSeek = Math.abs(mediaRef.current.currentTime - shouldBeTime) > 0.00001;
-        if (!playing || absoluteFrame === 0) {
+        if (pausedOrBuffering || absoluteFrame === 0) {
             if (makesSenseToSeek) {
                 seek(mediaRef, shouldBeTime);
             }
         }
-        if (mediaRef.current.paused && !mediaRef.current.ended && playing) {
+        if (mediaRef.current.paused &&
+            !mediaRef.current.ended &&
+            !pausedOrBuffering) {
             if (makesSenseToSeek) {
                 seek(mediaRef, shouldBeTime);
             }
@@ -101,13 +106,13 @@ const useMediaPlayback = ({ mediaRef, src, mediaType, playbackRate: localPlaybac
         frame,
         mediaRef,
         mediaType,
-        playing,
         src,
         mediaStartsAt,
         localPlaybackRate,
         onlyWarnForMediaSeekingError,
         acceptableTimeshift,
         acceptableTimeShiftButLessThanDuration,
+        pausedOrBuffering,
     ]);
 };
 exports.useMediaPlayback = useMediaPlayback;

package/dist/cjs/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "4.0.110";
+export declare const VERSION = "4.0.112";

package/dist/cjs/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // Automatically generated on publish
-exports.VERSION = '4.0.110';
+exports.VERSION = '4.0.112';

package/dist/cjs/video/OffthreadVideo.js

@@ -8,7 +8,7 @@ const Sequence_js_1 = require("../Sequence.js");
 const validate_media_props_js_1 = require("../validate-media-props.js");
 const validate_start_from_props_js_1 = require("../validate-start-from-props.js");
 const OffthreadVideoForRendering_js_1 = require("./OffthreadVideoForRendering.js");
-const VideoForDevelopment_js_1 = require("./VideoForDevelopment.js");
+const VideoForPreview_js_1 = require("./VideoForPreview.js");
 /**
  * @description This method imports and displays a video, similar to <Video />. During rendering, it extracts the exact frame from the video and displays it in an <img> tag
  * @see [Documentation](https://www.remotion.dev/docs/offthreadvideo)
@@ -16,7 +16,7 @@ const VideoForDevelopment_js_1 = require("./VideoForDevelopment.js");
 const OffthreadVideo = (props) => {
     // Should only destruct `startFrom` and `endAt` from props,
     // rest gets drilled down
-    const { startFrom, endAt, name, stack, ...otherProps } = props;
+    const { startFrom, endAt, name, pauseWhenBuffering, stack, ...otherProps } = props;
     const environment = (0, get_remotion_environment_js_1.getRemotionEnvironment)();
     const onDuration = (0, react_1.useCallback)(() => undefined, []);
     if (typeof props.src !== 'string') {
@@ -36,6 +36,6 @@ const OffthreadVideo = (props) => {
         return (0, jsx_runtime_1.jsx)(OffthreadVideoForRendering_js_1.OffthreadVideoForRendering, { ...otherProps });
     }
     const { transparent, ...withoutTransparent } = otherProps;
-    return ((0, jsx_runtime_1.jsx)(VideoForDevelopment_js_1.VideoForDevelopment, { _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, _remotionInternalNativeLoopPassed: false, onDuration: onDuration, onlyWarnForMediaSeekingError: true, ...withoutTransparent }));
+    return ((0, jsx_runtime_1.jsx)(VideoForPreview_js_1.VideoForPreview, { _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, _remotionInternalNativeLoopPassed: false, onDuration: onDuration, onlyWarnForMediaSeekingError: true, pauseWhenBuffering: pauseWhenBuffering !== null && pauseWhenBuffering !== void 0 ? pauseWhenBuffering : false, ...withoutTransparent }));
 };
 exports.OffthreadVideo = OffthreadVideo;

package/dist/cjs/video/Video.d.ts

@@ -11,6 +11,7 @@ export declare const Video: React.ForwardRefExoticComponent<Omit<Omit<React.Deta
     acceptableTimeShiftInSeconds?: number | undefined;
     allowAmplificationDuringRender?: boolean | undefined;
     toneFrequency?: number | undefined;
+    pauseWhenBuffering?: boolean | undefined;
 } & RemotionMainVideoProps & {
     /**
      * @deprecated For internal use only

package/dist/cjs/video/Video.js

@@ -15,11 +15,11 @@ const use_video_config_js_1 = require("../use-video-config.js");
 const validate_media_props_js_1 = require("../validate-media-props.js");
 const validate_start_from_props_js_1 = require("../validate-start-from-props.js");
 const duration_state_js_1 = require("./duration-state.js");
-const VideoForDevelopment_js_1 = require("./VideoForDevelopment.js");
+const VideoForPreview_js_1 = require("./VideoForPreview.js");
 const VideoForRendering_js_1 = require("./VideoForRendering.js");
 const VideoForwardingFunction = (props, ref) => {
     var _a, _b;
-    const { startFrom, endAt, name, stack, _remotionInternalNativeLoopPassed, ...otherProps } = props;
+    const { startFrom, endAt, name, pauseWhenBuffering, stack, _remotionInternalNativeLoopPassed, ...otherProps } = props;
     const { loop, ...propsOtherThanLoop } = props;
     const { fps } = (0, use_video_config_js_1.useVideoConfig)();
     const environment = (0, get_remotion_environment_js_1.getRemotionEnvironment)();
@@ -54,7 +54,9 @@ const VideoForwardingFunction = (props, ref) => {
     if (environment.isRendering) {
         return ((0, jsx_runtime_1.jsx)(VideoForRendering_js_1.VideoForRendering, { onDuration: onDuration, ...otherProps, ref: ref }));
     }
-    return ((0, jsx_runtime_1.jsx)(VideoForDevelopment_js_1.VideoForDevelopment, { onlyWarnForMediaSeekingError: false, ...otherProps, ref: ref, onDuration: onDuration, _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, _remotionInternalNativeLoopPassed: _remotionInternalNativeLoopPassed !== null && _remotionInternalNativeLoopPassed !== void 0 ? _remotionInternalNativeLoopPassed : false }));
+    return ((0, jsx_runtime_1.jsx)(VideoForPreview_js_1.VideoForPreview, { onlyWarnForMediaSeekingError: false, ...otherProps, ref: ref, 
+        // Proposal: Make this default to true in v5
+        pauseWhenBuffering: pauseWhenBuffering !== null && pauseWhenBuffering !== void 0 ? pauseWhenBuffering : false, onDuration: onDuration, _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, _remotionInternalNativeLoopPassed: _remotionInternalNativeLoopPassed !== null && _remotionInternalNativeLoopPassed !== void 0 ? _remotionInternalNativeLoopPassed : false }));
 };
 /**
  * @description allows you to include a video file in your Remotion project. It wraps the native HTMLVideoElement.

package/dist/cjs/video/VideoForRendering.d.ts

@@ -7,6 +7,7 @@ export declare const VideoForRendering: ForwardRefExoticComponent<Omit<React.Det
     acceptableTimeShiftInSeconds?: number | undefined;
     allowAmplificationDuringRender?: boolean | undefined;
     toneFrequency?: number | undefined;
+    pauseWhenBuffering?: boolean | undefined;
 } & {
     onDuration: (src: string, durationInSeconds: number) => void;
 } & RefAttributes<HTMLVideoElement>>;

package/dist/cjs/video/props.d.ts

@@ -15,6 +15,7 @@ export type RemotionVideoProps = Omit<React.DetailedHTMLProps<React.VideoHTMLAtt
     acceptableTimeShiftInSeconds?: number;
     allowAmplificationDuringRender?: boolean;
     toneFrequency?: number;
+    pauseWhenBuffering?: boolean;
 };
 type DeprecatedOffthreadVideoProps = {
     /**
@@ -36,6 +37,7 @@ export type OffthreadVideoProps = {
     allowAmplificationDuringRender?: boolean;
     toneFrequency?: number;
     transparent?: boolean;
+    pauseWhenBuffering?: boolean;
     /**
      * @deprecated For internal use only
      */

package/dist/cjs/wrap-remotion-context.d.ts

@@ -23,6 +23,20 @@ export declare function useRemotionContexts(): {
     } | null;
     renderAssetManagerContext: import("./RenderAssetManager.js").RenderAssetManagerContext;
     sequenceManagerContext: import("./SequenceManager.js").SequenceManagerContext;
+    bufferManagerContext: {
+        addBlock: (block: {
+            id: string;
+        }) => {
+            unblock: () => void;
+        };
+        listenForBuffering: (callback: () => void) => {
+            remove: () => void;
+        };
+        listenForResume: (callback: () => void) => {
+            remove: () => void;
+        };
+        buffering: React.MutableRefObject<boolean>;
+    } | null;
 };
 export interface RemotionContextProviderProps {
     contexts: ReturnType<typeof useRemotionContexts>;

package/dist/cjs/wrap-remotion-context.js

@@ -29,6 +29,7 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 // such as in React Three Fiber. All the contexts need to be passed again
 // for them to be useable
 const react_1 = __importStar(require("react"));
+const buffering_js_1 = require("./buffering.js");
 const CanUseRemotionHooks_js_1 = require("./CanUseRemotionHooks.js");
 const CompositionManagerContext_js_1 = require("./CompositionManagerContext.js");
 const NativeLayers_js_1 = require("./NativeLayers.js");
@@ -51,6 +52,7 @@ function useRemotionContexts() {
     const resolveCompositionContext = react_1.default.useContext(ResolveCompositionConfig_js_1.ResolveCompositionContext);
     const renderAssetManagerContext = react_1.default.useContext(RenderAssetManager_js_1.RenderAssetManager);
     const sequenceManagerContext = react_1.default.useContext(SequenceManager_js_1.SequenceManager);
+    const bufferManagerContext = react_1.default.useContext(buffering_js_1.BufferingContextReact);
     return (0, react_1.useMemo)(() => ({
         compositionManagerCtx,
         timelineContext,
@@ -63,6 +65,7 @@ function useRemotionContexts() {
         resolveCompositionContext,
         renderAssetManagerContext,
         sequenceManagerContext,
+        bufferManagerContext,
     }), [
         compositionManagerCtx,
         nonceContext,
@@ -75,11 +78,12 @@ function useRemotionContexts() {
         resolveCompositionContext,
         renderAssetManagerContext,
         sequenceManagerContext,
+        bufferManagerContext,
     ]);
 }
 exports.useRemotionContexts = useRemotionContexts;
 const RemotionContextProvider = (props) => {
     const { children, contexts } = props;
-    return ((0, jsx_runtime_1.jsx)(CanUseRemotionHooks_js_1.CanUseRemotionHooks.Provider, { value: contexts.canUseRemotionHooksContext, children: (0, jsx_runtime_1.jsx)(nonce_js_1.NonceContext.Provider, { value: contexts.nonceContext, children: (0, jsx_runtime_1.jsx)(NativeLayers_js_1.NativeLayersContext.Provider, { value: contexts.nativeLayersContext, children: (0, jsx_runtime_1.jsx)(prefetch_state_js_1.PreloadContext.Provider, { value: contexts.preloadContext, children: (0, jsx_runtime_1.jsx)(CompositionManagerContext_js_1.CompositionManager.Provider, { value: contexts.compositionManagerCtx, children: (0, jsx_runtime_1.jsx)(SequenceManager_js_1.SequenceManager.Provider, { value: contexts.sequenceManagerContext, children: (0, jsx_runtime_1.jsx)(RenderAssetManager_js_1.RenderAssetManager.Provider, { value: contexts.renderAssetManagerContext, children: (0, jsx_runtime_1.jsx)(ResolveCompositionConfig_js_1.ResolveCompositionContext.Provider, { value: contexts.resolveCompositionContext, children: (0, jsx_runtime_1.jsx)(timeline_position_state_js_1.TimelineContext.Provider, { value: contexts.timelineContext, children: (0, jsx_runtime_1.jsx)(timeline_position_state_js_1.SetTimelineContext.Provider, { value: contexts.setTimelineContext, children: (0, jsx_runtime_1.jsx)(SequenceContext_js_1.SequenceContext.Provider, { value: contexts.sequenceContext, children: children }) }) }) }) }) }) }) }) }) }) }));
+    return ((0, jsx_runtime_1.jsx)(CanUseRemotionHooks_js_1.CanUseRemotionHooks.Provider, { value: contexts.canUseRemotionHooksContext, children: (0, jsx_runtime_1.jsx)(nonce_js_1.NonceContext.Provider, { value: contexts.nonceContext, children: (0, jsx_runtime_1.jsx)(NativeLayers_js_1.NativeLayersContext.Provider, { value: contexts.nativeLayersContext, children: (0, jsx_runtime_1.jsx)(prefetch_state_js_1.PreloadContext.Provider, { value: contexts.preloadContext, children: (0, jsx_runtime_1.jsx)(CompositionManagerContext_js_1.CompositionManager.Provider, { value: contexts.compositionManagerCtx, children: (0, jsx_runtime_1.jsx)(SequenceManager_js_1.SequenceManager.Provider, { value: contexts.sequenceManagerContext, children: (0, jsx_runtime_1.jsx)(RenderAssetManager_js_1.RenderAssetManager.Provider, { value: contexts.renderAssetManagerContext, children: (0, jsx_runtime_1.jsx)(ResolveCompositionConfig_js_1.ResolveCompositionContext.Provider, { value: contexts.resolveCompositionContext, children: (0, jsx_runtime_1.jsx)(timeline_position_state_js_1.TimelineContext.Provider, { value: contexts.timelineContext, children: (0, jsx_runtime_1.jsx)(timeline_position_state_js_1.SetTimelineContext.Provider, { value: contexts.setTimelineContext, children: (0, jsx_runtime_1.jsx)(SequenceContext_js_1.SequenceContext.Provider, { value: contexts.sequenceContext, children: (0, jsx_runtime_1.jsx)(buffering_js_1.BufferingContextReact.Provider, { value: contexts.bufferManagerContext, children: children }) }) }) }) }) }) }) }) }) }) }) }));
 };
 exports.RemotionContextProvider = RemotionContextProvider;

package/dist/esm/index.mjs

@@ -105,7 +105,7 @@ function truthy(value) {
 }
 
 // Automatically generated on publish
-const VERSION = '4.0.110';
+const VERSION = '4.0.112';
 
 const checkMultipleRemotionVersions = () => {
     if (typeof globalThis === 'undefined') {
@@ -1492,6 +1492,105 @@ const random = (seed, dummy) => {
     throw new Error('random() argument must be a number or a string');
 };
 
+const useBufferManager = () => {
+    const [blocks, setBlocks] = useState([]);
+    const [onBufferingCallbacks, setOnBufferingCallbacks] = useState([]);
+    const [onResumeCallbacks, setOnResumeCallbacks] = useState([]);
+    const buffering = useRef(false);
+    const addBlock = useCallback((block) => {
+        setBlocks((b) => [...b, block]);
+        return {
+            unblock: () => {
+                setBlocks((b) => b.filter((bx) => bx !== block));
+            },
+        };
+    }, []);
+    const listenForBuffering = useCallback((callback) => {
+        setOnBufferingCallbacks((c) => [...c, callback]);
+        return {
+            remove: () => {
+                setOnBufferingCallbacks((c) => c.filter((cb) => cb !== callback));
+            },
+        };
+    }, []);
+    const listenForResume = useCallback((callback) => {
+        setOnResumeCallbacks((c) => [...c, callback]);
+        return {
+            remove: () => {
+                setOnResumeCallbacks((c) => c.filter((cb) => cb !== callback));
+            },
+        };
+    }, []);
+    useEffect(() => {
+        if (blocks.length > 0) {
+            onBufferingCallbacks.forEach((c) => c());
+        }
+        else {
+            onResumeCallbacks.forEach((c) => c());
+        }
+    }, [blocks, onBufferingCallbacks, onResumeCallbacks]);
+    return useMemo(() => {
+        return { addBlock, listenForBuffering, listenForResume, buffering };
+    }, [addBlock, buffering, listenForBuffering, listenForResume]);
+};
+const BufferingContextReact = React.createContext(null);
+const BufferingProvider = ({ children }) => {
+    const bufferManager = useBufferManager();
+    return (jsx(BufferingContextReact.Provider, { value: bufferManager, children: children }));
+};
+
+const useBufferState = () => {
+    const buffer = useContext(BufferingContextReact);
+    return useMemo(() => ({
+        delayPlayback: () => {
+            if (!buffer) {
+                throw new Error('Tried to enable the buffering state, but a Remotion context was not found. This API can only be called in a component that was passed to the Remotion Player or a <Composition>. Or you might have experienced a version mismatch - run `npx remotion versions` and ensure all packages have the same version. This error is thrown by the buffer state https://remotion.dev/docs/player/buffer-state');
+            }
+            const { unblock } = buffer.addBlock({
+                id: String(Math.random()),
+            });
+            return { unblock };
+        },
+    }), [buffer]);
+};
+
+const useMediaBuffering = (element, shouldBuffer) => {
+    const buffer = useBufferState();
+    useEffect(() => {
+        let cleanup = () => undefined;
+        const { current } = element;
+        if (!current) {
+            return;
+        }
+        if (!shouldBuffer) {
+            return;
+        }
+        const onWaiting = () => {
+            const { unblock } = buffer.delayPlayback();
+            const onCanPlay = () => {
+                unblock();
+            };
+            current.addEventListener('canplay', onCanPlay, {
+                once: true,
+            });
+            cleanup = () => {
+                current.removeEventListener('canplay', onCanPlay);
+                unblock();
+                return undefined;
+            };
+        };
+        if (current.readyState < current.HAVE_FUTURE_DATA) {
+            onWaiting();
+        }
+        else {
+            current.addEventListener('waiting', onWaiting);
+        }
+        return () => {
+            cleanup();
+        };
+    }, [buffer, element, shouldBuffer]);
+};
+
 const useMediaStartsAt = () => {
     var _a;
     const parentSequence = useContext(SequenceContext);
@@ -1940,6 +2039,7 @@ const useMediaPlayback = ({ mediaRef, src, mediaType, playbackRate: localPlaybac
     const frame = useCurrentFrame();
     const absoluteFrame = useTimelinePosition();
     const [playing] = usePlayingState();
+    const buffering = useContext(BufferingContextReact);
     const { fps } = useVideoConfig();
     const mediaStartsAt = useMediaStartsAt();
     const playbackRate = localPlaybackRate * globalPlaybackRate;
@@ -1951,12 +2051,13 @@ const useMediaPlayback = ({ mediaRef, src, mediaType, playbackRate: localPlaybac
         }
         return acceptableTimeshift;
     })();
+    const pausedOrBuffering = !playing || (buffering && buffering.buffering);
     useEffect(() => {
         var _a;
-        if (!playing) {
+        if (pausedOrBuffering) {
             (_a = mediaRef.current) === null || _a === void 0 ? void 0 : _a.pause();
         }
-    }, [mediaRef, mediaType, playing]);
+    }, [mediaRef, mediaType, pausedOrBuffering]);
     useEffect(() => {
         const tagName = mediaType === 'audio' ? '<Audio>' : '<Video>';
         if (!mediaRef.current) {
@@ -1996,12 +2097,14 @@ const useMediaPlayback = ({ mediaRef, src, mediaType, playbackRate: localPlaybac
         // Refer to the https://github.com/remotion-dev/video-buffering-example
         // which is fixed by only seeking conditionally.
         const makesSenseToSeek = Math.abs(mediaRef.current.currentTime - shouldBeTime) > 0.00001;
-        if (!playing || absoluteFrame === 0) {
+        if (pausedOrBuffering || absoluteFrame === 0) {
             if (makesSenseToSeek) {
                 seek(mediaRef, shouldBeTime);
             }
         }
-        if (mediaRef.current.paused && !mediaRef.current.ended && playing) {
+        if (mediaRef.current.paused &&
+            !mediaRef.current.ended &&
+            !pausedOrBuffering) {
             if (makesSenseToSeek) {
                 seek(mediaRef, shouldBeTime);
             }
@@ -2014,13 +2117,13 @@ const useMediaPlayback = ({ mediaRef, src, mediaType, playbackRate: localPlaybac
         frame,
         mediaRef,
         mediaType,
-        playing,
         src,
         mediaStartsAt,
         localPlaybackRate,
         onlyWarnForMediaSeekingError,
         acceptableTimeshift,
         acceptableTimeShiftButLessThanDuration,
+        pausedOrBuffering,
     ]);
 };
 
@@ -2322,7 +2425,7 @@ const AudioForDevelopmentForwardRefFunction = (props, ref) => {
     const [mediaVolume] = useMediaVolumeState();
     const [mediaMuted] = useMediaMutedState();
     const volumePropFrame = useFrameForVolumeProp();
-    const { volume, muted, playbackRate, shouldPreMountAudioTags, src, onDuration, acceptableTimeShiftInSeconds, _remotionInternalNeedsDurationCalculation, _remotionInternalNativeLoopPassed, _remotionInternalStack, allowAmplificationDuringRender, name, ...nativeProps } = props;
+    const { volume, muted, playbackRate, shouldPreMountAudioTags, src, onDuration, acceptableTimeShiftInSeconds, _remotionInternalNeedsDurationCalculation, _remotionInternalNativeLoopPassed, _remotionInternalStack, allowAmplificationDuringRender, name, pauseWhenBuffering, ...nativeProps } = props;
     const { hidden } = useContext(SequenceVisibilityToggleContext);
     if (!src) {
         throw new TypeError("No 'src' was passed to <Audio>.");
@@ -2384,6 +2487,7 @@ const AudioForDevelopmentForwardRefFunction = (props, ref) => {
         onlyWarnForMediaSeekingError: false,
         acceptableTimeshift: acceptableTimeShiftInSeconds !== null && acceptableTimeShiftInSeconds !== void 0 ? acceptableTimeShiftInSeconds : DEFAULT_ACCEPTABLE_TIMESHIFT,
     });
+    useMediaBuffering(audioRef, pauseWhenBuffering);
     useImperativeHandle(ref, () => {
         return audioRef.current;
     }, [audioRef]);
@@ -2413,7 +2517,7 @@ const AudioForDevelopmentForwardRefFunction = (props, ref) => {
     }
     return jsx("audio", { ref: audioRef, preload: "metadata", ...propsToPass });
 };
-const AudioForDevelopment = forwardRef(AudioForDevelopmentForwardRefFunction);
+const AudioForPreview = forwardRef(AudioForDevelopmentForwardRefFunction);
 
 if (typeof window !== 'undefined') {
     window.remotion_renderReady = false;
@@ -2642,7 +2746,7 @@ const AudioForRendering = forwardRef(AudioForRenderingRefForwardingFunction);
 const AudioRefForwardingFunction = (props, ref) => {
     var _a, _b, _c;
     const audioContext = useContext(SharedAudioContext);
-    const { startFrom, endAt, name, stack, ...otherProps } = props;
+    const { startFrom, endAt, name, stack, pauseWhenBuffering, ...otherProps } = props;
     const { loop, ...propsOtherThanLoop } = props;
     const { fps } = useVideoConfig();
     const environment = getRemotionEnvironment();
@@ -2688,7 +2792,9 @@ const AudioRefForwardingFunction = (props, ref) => {
     if (environment.isRendering) {
         return (jsx(AudioForRendering, { onDuration: onDuration, ...props, ref: ref, onError: onError, _remotionInternalNeedsDurationCalculation: Boolean(loop) }));
     }
-    return (jsx(AudioForDevelopment, { _remotionInternalNativeLoopPassed: (_c = props._remotionInternalNativeLoopPassed) !== null && _c !== void 0 ? _c : false, _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, shouldPreMountAudioTags: audioContext !== null && audioContext.numberOfAudioTags > 0, ...props, ref: ref, onError: onError, onDuration: onDuration, _remotionInternalNeedsDurationCalculation: Boolean(loop) }));
+    return (jsx(AudioForPreview, { _remotionInternalNativeLoopPassed: (_c = props._remotionInternalNativeLoopPassed) !== null && _c !== void 0 ? _c : false, _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, shouldPreMountAudioTags: audioContext !== null && audioContext.numberOfAudioTags > 0, ...props, ref: ref, onError: onError, onDuration: onDuration, 
+        // Proposal: Make this default to true in v5
+        pauseWhenBuffering: pauseWhenBuffering !== null && pauseWhenBuffering !== void 0 ? pauseWhenBuffering : false, _remotionInternalNeedsDurationCalculation: Boolean(loop) }));
 };
 /**
  * @description With this component, you can add audio to your video. All audio formats which are supported by Chromium are supported by the component.
@@ -3221,9 +3327,10 @@ const IFrame = forwardRef(IFrameRefForwarding);
 function exponentialBackoff(errorCount) {
     return 1000 * 2 ** (errorCount - 1);
 }
-const ImgRefForwarding = ({ onError, maxRetries = 2, src, ...props }, ref) => {
+const ImgRefForwarding = ({ onError, maxRetries = 2, src, pauseWhenLoading, ...props }, ref) => {
     const imageRef = useRef(null);
     const errors = useRef({});
+    const { delayPlayback } = useBufferState();
     if (!src) {
         throw new Error('No "src" prop was passed to <Img>.');
     }
@@ -3279,6 +3386,9 @@ const ImgRefForwarding = ({ onError, maxRetries = 2, src, ...props }, ref) => {
                 return;
             }
             const newHandle = delayRender('Loading <Img> with src=' + actualSrc);
+            const unblock = pauseWhenLoading
+                ? delayPlayback().unblock
+                : () => undefined;
             const { current } = imageRef;
             const onComplete = () => {
                 var _a, _b, _c, _d;
@@ -3287,6 +3397,7 @@ const ImgRefForwarding = ({ onError, maxRetries = 2, src, ...props }, ref) => {
                     // eslint-disable-next-line no-console
                     console.info(`Retry successful - ${(_d = imageRef.current) === null || _d === void 0 ? void 0 : _d.src} is now loaded`);
                 }
+                unblock();
                 continueRender(newHandle);
             };
             const didLoad = () => {
@@ -3301,9 +3412,10 @@ const ImgRefForwarding = ({ onError, maxRetries = 2, src, ...props }, ref) => {
             // If tag gets unmounted, clear pending handles because image is not going to load
             return () => {
                 current === null || current === void 0 ? void 0 : current.removeEventListener('load', didLoad);
+                unblock();
                 continueRender(newHandle);
             };
-        }, [actualSrc]);
+        }, [actualSrc, delayPlayback, pauseWhenLoading]);
     }
     return (jsx("img", { ...props, ref: imageRef, src: actualSrc, onError: didGetError }));
 };
@@ -3939,7 +4051,7 @@ const RemotionRoot = ({ children, numberOfAudioTags }) => {
             }
         }
     }, []);
-    return (jsx(NonceContext.Provider, { value: nonceContext, children: jsx(TimelineContext.Provider, { value: timelineContextValue, children: jsx(SetTimelineContext.Provider, { value: setTimelineContextValue, children: jsx(EditorPropsProvider, { children: jsx(PrefetchProvider, { children: jsx(NativeLayersProvider, { children: jsx(CompositionManagerProvider, { numberOfAudioTags: numberOfAudioTags, children: jsx(DurationsContextProvider, { children: children }) }) }) }) }) }) }) }));
+    return (jsx(NonceContext.Provider, { value: nonceContext, children: jsx(TimelineContext.Provider, { value: timelineContextValue, children: jsx(SetTimelineContext.Provider, { value: setTimelineContextValue, children: jsx(EditorPropsProvider, { children: jsx(PrefetchProvider, { children: jsx(NativeLayersProvider, { children: jsx(CompositionManagerProvider, { numberOfAudioTags: numberOfAudioTags, children: jsx(DurationsContextProvider, { children: jsx(BufferingProvider, { children: children }) }) }) }) }) }) }) }) }));
 };
 
 const getEnvVariables = () => {
@@ -3974,6 +4086,47 @@ const setupEnvVariables = () => {
     });
 };
 
+const CurrentScaleContext = React.createContext(null);
+const PreviewSizeContext = createContext({
+    setSize: () => undefined,
+    size: { size: 'auto', translation: { x: 0, y: 0 } },
+});
+const calculateScale = ({ canvasSize, compositionHeight, compositionWidth, previewSize, }) => {
+    const heightRatio = canvasSize.height / compositionHeight;
+    const widthRatio = canvasSize.width / compositionWidth;
+    const ratio = Math.min(heightRatio, widthRatio);
+    return previewSize === 'auto' ? ratio : Number(previewSize);
+};
+/**
+ * Gets the current scale of the container in which the component is being rendered.
+ * Only works in the Remotion Studio and in the Remotion Player.
+ */
+const useCurrentScale = (options) => {
+    const hasContext = React.useContext(CurrentScaleContext);
+    const zoomContext = React.useContext(PreviewSizeContext);
+    const config = useUnsafeVideoConfig();
+    if (hasContext === null || config === null || zoomContext === null) {
+        if (options === null || options === void 0 ? void 0 : options.dontThrowIfOutsideOfRemotion) {
+            return 1;
+        }
+        throw new Error([
+            'useCurrentScale() was called outside of a Remotion context.',
+            'This hook can only be called in a component that is being rendered by Remotion.',
+            'If you want to this hook to return 1 outside of Remotion, pass {dontThrowIfOutsideOfRemotion: true} as an option.',
+            'If you think you called this hook in a Remotion component, make sure all versions of Remotion are aligned.',
+        ].join('\n'));
+    }
+    if (hasContext.type === 'scale') {
+        return hasContext.scale;
+    }
+    return calculateScale({
+        canvasSize: hasContext.canvasSize,
+        compositionHeight: config.height,
+        compositionWidth: config.width,
+        previewSize: zoomContext.size.size,
+    });
+};
+
 const WATCH_REMOTION_STATIC_FILES = 'remotion_staticFilesChanged';
 /**
  * @description Watch for changes in a specific static file.
@@ -4028,6 +4181,7 @@ function useRemotionContexts() {
     const resolveCompositionContext = React.useContext(ResolveCompositionContext);
     const renderAssetManagerContext = React.useContext(RenderAssetManager);
     const sequenceManagerContext = React.useContext(SequenceManager);
+    const bufferManagerContext = React.useContext(BufferingContextReact);
     return useMemo(() => ({
         compositionManagerCtx,
         timelineContext,
@@ -4040,6 +4194,7 @@ function useRemotionContexts() {
         resolveCompositionContext,
         renderAssetManagerContext,
         sequenceManagerContext,
+        bufferManagerContext,
     }), [
         compositionManagerCtx,
         nonceContext,
@@ -4052,11 +4207,12 @@ function useRemotionContexts() {
         resolveCompositionContext,
         renderAssetManagerContext,
         sequenceManagerContext,
+        bufferManagerContext,
     ]);
 }
 const RemotionContextProvider = (props) => {
     const { children, contexts } = props;
-    return (jsx(CanUseRemotionHooks.Provider, { value: contexts.canUseRemotionHooksContext, children: jsx(NonceContext.Provider, { value: contexts.nonceContext, children: jsx(NativeLayersContext.Provider, { value: contexts.nativeLayersContext, children: jsx(PreloadContext.Provider, { value: contexts.preloadContext, children: jsx(CompositionManager.Provider, { value: contexts.compositionManagerCtx, children: jsx(SequenceManager.Provider, { value: contexts.sequenceManagerContext, children: jsx(RenderAssetManager.Provider, { value: contexts.renderAssetManagerContext, children: jsx(ResolveCompositionContext.Provider, { value: contexts.resolveCompositionContext, children: jsx(TimelineContext.Provider, { value: contexts.timelineContext, children: jsx(SetTimelineContext.Provider, { value: contexts.setTimelineContext, children: jsx(SequenceContext.Provider, { value: contexts.sequenceContext, children: children }) }) }) }) }) }) }) }) }) }) }));
+    return (jsx(CanUseRemotionHooks.Provider, { value: contexts.canUseRemotionHooksContext, children: jsx(NonceContext.Provider, { value: contexts.nonceContext, children: jsx(NativeLayersContext.Provider, { value: contexts.nativeLayersContext, children: jsx(PreloadContext.Provider, { value: contexts.preloadContext, children: jsx(CompositionManager.Provider, { value: contexts.compositionManagerCtx, children: jsx(SequenceManager.Provider, { value: contexts.sequenceManagerContext, children: jsx(RenderAssetManager.Provider, { value: contexts.renderAssetManagerContext, children: jsx(ResolveCompositionContext.Provider, { value: contexts.resolveCompositionContext, children: jsx(TimelineContext.Provider, { value: contexts.timelineContext, children: jsx(SetTimelineContext.Provider, { value: contexts.setTimelineContext, children: jsx(SequenceContext.Provider, { value: contexts.sequenceContext, children: jsx(BufferingContextReact.Provider, { value: contexts.bufferManagerContext, children: children }) }) }) }) }) }) }) }) }) }) }) }));
 };
 
 // Mark them as Internals so use don't assume this is public
@@ -4116,8 +4272,13 @@ const Internals = {
     WATCH_REMOTION_STATIC_FILES,
     addSequenceStackTraces,
     useMediaStartsAt,
+    BufferingProvider,
+    BufferingContextReact,
     enableSequenceStackTraces,
     colorNames,
+    CurrentScaleContext,
+    PreviewSizeContext,
+    calculateScale,
 };
 
 const validateFrame = ({ allowFloats, durationInFrames, frame, }) => {
@@ -4601,7 +4762,7 @@ const VideoForDevelopmentRefForwardingFunction = (props, ref) => {
     const isSequenceHidden = (_a = hidden[timelineId]) !== null && _a !== void 0 ? _a : false;
     const { volume, muted, playbackRate, onlyWarnForMediaSeekingError, src, onDuration, 
     // @ts-expect-error
-    acceptableTimeShift, acceptableTimeShiftInSeconds, toneFrequency, name, _remotionInternalNativeLoopPassed, _remotionInternalStack, style, ...nativeProps } = props;
+    acceptableTimeShift, acceptableTimeShiftInSeconds, toneFrequency, name, _remotionInternalNativeLoopPassed, _remotionInternalStack, style, pauseWhenBuffering, ...nativeProps } = props;
     if (typeof acceptableTimeShift !== 'undefined') {
         throw new Error('acceptableTimeShift has been removed. Use acceptableTimeShiftInSeconds instead.');
     }
@@ -4634,6 +4795,7 @@ const VideoForDevelopmentRefForwardingFunction = (props, ref) => {
         onlyWarnForMediaSeekingError,
         acceptableTimeshift: acceptableTimeShiftInSeconds !== null && acceptableTimeShiftInSeconds !== void 0 ? acceptableTimeShiftInSeconds : DEFAULT_ACCEPTABLE_TIMESHIFT,
     });
+    useMediaBuffering(videoRef, pauseWhenBuffering);
     const actualFrom = parentSequence
         ? parentSequence.relativeFrom + parentSequence.cumulatedFrom
         : 0;
@@ -4721,8 +4883,7 @@ const VideoForDevelopmentRefForwardingFunction = (props, ref) => {
     }, [isSequenceHidden, style]);
     return (jsx("video", { ref: videoRef, muted: muted || mediaMuted, playsInline: true, src: actualSrc, loop: _remotionInternalNativeLoopPassed, style: actualStyle, ...nativeProps }));
 };
-// Copy types from forwardRef but not necessary to remove ref
-const VideoForDevelopment = forwardRef(VideoForDevelopmentRefForwardingFunction);
+const VideoForPreview = forwardRef(VideoForDevelopmentRefForwardingFunction);
 
 /**
  * @description This method imports and displays a video, similar to <Video />. During rendering, it extracts the exact frame from the video and displays it in an <img> tag
@@ -4731,7 +4892,7 @@ const VideoForDevelopment = forwardRef(VideoForDevelopmentRefForwardingFunction)
 const OffthreadVideo = (props) => {
     // Should only destruct `startFrom` and `endAt` from props,
     // rest gets drilled down
-    const { startFrom, endAt, name, stack, ...otherProps } = props;
+    const { startFrom, endAt, name, pauseWhenBuffering, stack, ...otherProps } = props;
     const environment = getRemotionEnvironment();
     const onDuration = useCallback(() => undefined, []);
     if (typeof props.src !== 'string') {
@@ -4751,7 +4912,7 @@ const OffthreadVideo = (props) => {
         return jsx(OffthreadVideoForRendering, { ...otherProps });
     }
     const { transparent, ...withoutTransparent } = otherProps;
-    return (jsx(VideoForDevelopment, { _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, _remotionInternalNativeLoopPassed: false, onDuration: onDuration, onlyWarnForMediaSeekingError: true, ...withoutTransparent }));
+    return (jsx(VideoForPreview, { _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, _remotionInternalNativeLoopPassed: false, onDuration: onDuration, onlyWarnForMediaSeekingError: true, pauseWhenBuffering: pauseWhenBuffering !== null && pauseWhenBuffering !== void 0 ? pauseWhenBuffering : false, ...withoutTransparent }));
 };
 
 const roundTo6Commas = (num) => {
@@ -5022,7 +5183,7 @@ const VideoForRendering = forwardRef(VideoForRenderingForwardFunction);
 
 const VideoForwardingFunction = (props, ref) => {
     var _a, _b;
-    const { startFrom, endAt, name, stack, _remotionInternalNativeLoopPassed, ...otherProps } = props;
+    const { startFrom, endAt, name, pauseWhenBuffering, stack, _remotionInternalNativeLoopPassed, ...otherProps } = props;
     const { loop, ...propsOtherThanLoop } = props;
     const { fps } = useVideoConfig();
     const environment = getRemotionEnvironment();
@@ -5057,7 +5218,9 @@ const VideoForwardingFunction = (props, ref) => {
     if (environment.isRendering) {
         return (jsx(VideoForRendering, { onDuration: onDuration, ...otherProps, ref: ref }));
     }
-    return (jsx(VideoForDevelopment, { onlyWarnForMediaSeekingError: false, ...otherProps, ref: ref, onDuration: onDuration, _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, _remotionInternalNativeLoopPassed: _remotionInternalNativeLoopPassed !== null && _remotionInternalNativeLoopPassed !== void 0 ? _remotionInternalNativeLoopPassed : false }));
+    return (jsx(VideoForPreview, { onlyWarnForMediaSeekingError: false, ...otherProps, ref: ref, 
+        // Proposal: Make this default to true in v5
+        pauseWhenBuffering: pauseWhenBuffering !== null && pauseWhenBuffering !== void 0 ? pauseWhenBuffering : false, onDuration: onDuration, _remotionInternalStack: stack !== null && stack !== void 0 ? stack : null, _remotionInternalNativeLoopPassed: _remotionInternalNativeLoopPassed !== null && _remotionInternalNativeLoopPassed !== void 0 ? _remotionInternalNativeLoopPassed : false }));
 };
 /**
  * @description allows you to include a video file in your Remotion project. It wraps the native HTMLVideoElement.
@@ -5108,4 +5271,4 @@ const Config = new Proxy(proxyObj, {
 });
 addSequenceStackTraces(Sequence);
 
-export { AbsoluteFill, Audio, Composition, Config, Easing, Experimental, Folder, FolderContext, Freeze, IFrame, Img, Internals, Loop, OffthreadVideo, Sequence, Series, Still, VERSION, Video, cancelRender, continueRender, delayRender, getInputProps, getRemotionEnvironment, getStaticFiles, interpolate, interpolateColors, measureSpring, prefetch, random, registerRoot, spring, staticFile, useCurrentFrame, useVideoConfig, watchStaticFile };
+export { AbsoluteFill, Audio, Composition, Config, Easing, Experimental, Folder, FolderContext, Freeze, IFrame, Img, Internals, Loop, OffthreadVideo, Sequence, Series, Still, VERSION, Video, cancelRender, continueRender, delayRender, getInputProps, getRemotionEnvironment, getStaticFiles, interpolate, interpolateColors, measureSpring, prefetch, random, registerRoot, spring, staticFile, useBufferState, useCurrentFrame, useCurrentScale, useVideoConfig, watchStaticFile };

package/dist/esm/version.mjs

@@ -1,4 +1,4 @@
 // Automatically generated on publish
-const VERSION = '4.0.110';
+const VERSION = '4.0.112';
 
 export { VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remotion",
-  "version": "4.0.110",
+  "version": "4.0.112",
   "description": "Render videos in React",
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",