Player: getScale() and initially show controls before fading out

packages/docs/docs/player/api.md

@@ -281,6 +281,12 @@ _optional, available from v3.2.15_
 
 Limit playback to only play before a certain frame. The video will end at this frame and move to the beginning once it has ended. Must be an integer, not smaller than `1`, not smaller than [`inFrame`](#inframe) and not bigger than `durationInFrames - 1`. Default `null`, which means the end of the video.
 
+### `initiallyShowControls`
+
+_optional, available from v3.2.24_
+
+If true, the controls flash when the player enters the scene. After 2 seconds without hover, the controls fade out. This is similar to how YouTube does it, and signals to the user that the player is in fact controllable. You can also pass a `number`, with which you can customize the duration in milliseconds. Default `true` since `v3.2.24`, before that unsupported.
+
 ## `PlayerRef`
 
 You may attach a ref to the player and control it in an imperative manner.
@@ -432,6 +438,12 @@ Requests the video to go to fullscreen. This method throws if the `allowFullscre
 
 Exit fullscreen mode.
 
+### `getScale()`
+
+_available since v3.2.24_
+
+Returns a number which says how much the content is scaled down compared to the natural composition size. For example, if the composition is `1920x1080`, but the player is 960px in width, this method would return `0.5`.
+
 ### `addEventListener()`
 
 Start listening to an event. See the [Events](#events) section to see the function signature and the available events.

packages/player-example/src/index.tsx

@@ -2,7 +2,6 @@ import React, {ComponentType} from 'react';
 import {createRoot} from 'react-dom/client';
 import App from './App';
 import CarSlideshow from './CarSlideshow';
-import {MyAudio} from './MyAudio';
 import {VideoautoplayDemo} from './VideoAutoplay';
 
 const rootElement = document.getElementById('root');
@@ -28,7 +27,6 @@ createRoot(rootElement as HTMLElement).render(
 		}}
 	>
 		<React.StrictMode>
-			<MyAudio />
 			<App lazyComponent={Car} durationInFrames={500} />
 			<App component={VideoautoplayDemo} durationInFrames={2700} />
 		</React.StrictMode>

packages/player/src/Player.tsx

@@ -67,6 +67,7 @@ export type PlayerProps<T> = {
 	showPosterWhenUnplayed?: boolean;
 	inFrame?: number | null;
 	outFrame?: number | null;
+	initiallyShowControls?: number | boolean;
 } & PropsIfHasProps<T> &
 	CompProps<T>;
 
@@ -109,6 +110,7 @@ export const PlayerFn = <T,>(
 		renderPoster,
 		inFrame,
 		outFrame,
+		initiallyShowControls,
 		...componentProps
 	}: PlayerProps<T>,
 	ref: MutableRefObject<PlayerRef>
@@ -428,6 +430,7 @@ export const PlayerFn = <T,>(
 												renderPoster={renderPoster}
 												inFrame={inFrame ?? null}
 												outFrame={outFrame ?? null}
+												initiallyShowControls={initiallyShowControls ?? true}
 											/>
 										</Internals.PrefetchProvider>
 									</PlayerEventEmitterContext.Provider>

packages/player/src/PlayerControls.tsx

@@ -96,6 +96,7 @@ export const Controls: React.FC<{
 	onSeekStart: () => void;
 	inFrame: number | null;
 	outFrame: number | null;
+	initiallyShowControls: number | boolean;
 }> = ({
 	durationInFrames,
 	hovered,
@@ -111,19 +112,51 @@ export const Controls: React.FC<{
 	onSeekStart,
 	inFrame,
 	outFrame,
+	initiallyShowControls,
 }) => {
 	const playButtonRef = useRef<HTMLButtonElement | null>(null);
 	const frame = Internals.Timeline.useTimelinePosition();
 	const [supportsFullscreen, setSupportsFullscreen] = useState(false);
+	const [shouldShowInitially, setInitiallyShowControls] = useState<
+		boolean | number
+	>(() => {
+		if (typeof initiallyShowControls === 'boolean') {
+			return initiallyShowControls;
+		}
+
+		if (typeof initiallyShowControls === 'number') {
+			if (initiallyShowControls % 1 !== 0) {
+				throw new Error(
+					'initiallyShowControls must be an integer or a boolean'
+				);
+			}
+
+			if (Number.isNaN(initiallyShowControls)) {
+				throw new Error('initiallyShowControls must not be NaN');
+			}
+
+			if (!Number.isFinite(initiallyShowControls)) {
+				throw new Error('initiallyShowControls must be finite');
+			}
+
+			if (initiallyShowControls <= 0) {
+				throw new Error('initiallyShowControls must be a positive integer');
+			}
+
+			return initiallyShowControls;
+		}
+
+		throw new TypeError('initiallyShowControls must be a number or a boolean');
+	});
 
 	const containerCss: React.CSSProperties = useMemo(() => {
 		// Hide if playing and mouse outside
-		const shouldShow = hovered || !player.playing;
+		const shouldShow = hovered || !player.playing || shouldShowInitially;
 		return {
 			...containerStyle,
 			opacity: Number(shouldShow),
 		};
-	}, [hovered, player.playing]);
+	}, [hovered, shouldShowInitially, player.playing]);
 
 	useEffect(() => {
 		if (playButtonRef.current && spaceKeyToPlayOrPause) {
@@ -143,6 +176,21 @@ export const Controls: React.FC<{
 		);
 	}, []);
 
+	useEffect(() => {
+		if (shouldShowInitially === false) {
+			return;
+		}
+
+		const time = shouldShowInitially === true ? 2000 : shouldShowInitially;
+		const timeout = setTimeout(() => {
+			setInitiallyShowControls(false);
+		}, time);
+
+		return () => {
+			clearInterval(timeout);
+		};
+	}, [shouldShowInitially]);
+
 	return (
 		<div style={containerCss}>
 			<div style={controlsRow}>

packages/player/src/PlayerUI.tsx

@@ -67,6 +67,7 @@ const PlayerUI: React.ForwardRefRenderFunction<
 		showPosterWhenUnplayed: boolean;
 		inFrame: number | null;
 		outFrame: number | null;
+		initiallyShowControls: number | boolean;
 	}
 > = (
 	{
@@ -95,6 +96,7 @@ const PlayerUI: React.ForwardRefRenderFunction<
 		showPosterWhenPaused,
 		inFrame,
 		outFrame,
+		initiallyShowControls,
 	},
 	ref
 ) => {
@@ -227,6 +229,20 @@ const PlayerUI: React.ForwardRefRenderFunction<
 
 	const durationInFrames = config?.durationInFrames ?? 1;
 
+	const layout = useMemo(() => {
+		if (!config || !canvasSize) {
+			return null;
+		}
+
+		return calculateCanvasTransformation({
+			canvasSize,
+			compositionHeight: config.height,
+			compositionWidth: config.width,
+			previewSize: 'auto',
+		});
+	}, [canvasSize, config]);
+	const scale = layout?.scale ?? 1;
+
 	useImperativeHandle(
 		ref,
 		() => {
@@ -290,6 +306,7 @@ const PlayerUI: React.ForwardRefRenderFunction<
 				unmute: () => {
 					setMediaMuted(false);
 				},
+				getScale: () => scale,
 			};
 			return Object.assign(player.emitter, methods);
 		},
@@ -305,6 +322,7 @@ const PlayerUI: React.ForwardRefRenderFunction<
 			setMediaMuted,
 			setMediaVolume,
 			toggle,
+			scale,
 		]
 	);
 
@@ -329,25 +347,12 @@ const PlayerUI: React.ForwardRefRenderFunction<
 		};
 	}, [canvasSize, config, style]);
 
-	const layout = useMemo(() => {
-		if (!config || !canvasSize) {
-			return null;
-		}
-
-		return calculateCanvasTransformation({
-			canvasSize,
-			compositionHeight: config.height,
-			compositionWidth: config.width,
-			previewSize: 'auto',
-		});
-	}, [canvasSize, config]);
-
 	const outer: React.CSSProperties = useMemo(() => {
 		if (!layout || !config) {
 			return {};
 		}
 
-		const {centerX, centerY, scale} = layout;
+		const {centerX, centerY} = layout;
 
 		return {
 			width: config.width * scale,
@@ -359,31 +364,24 @@ const PlayerUI: React.ForwardRefRenderFunction<
 			top: centerY,
 			overflow: 'hidden',
 		};
-	}, [config, layout]);
+	}, [config, layout, scale]);
 
 	const containerStyle: React.CSSProperties = useMemo(() => {
-		if (!config || !canvasSize) {
+		if (!config || !canvasSize || !layout) {
 			return {};
 		}
 
-		const {scale, xCorrection, yCorrection} = calculateCanvasTransformation({
-			canvasSize,
-			compositionHeight: config.height,
-			compositionWidth: config.width,
-			previewSize: 'auto',
-		});
-
 		return {
 			position: 'absolute',
 			width: config.width,
 			height: config.height,
 			display: 'flex',
 			transform: `scale(${scale})`,
-			marginLeft: xCorrection,
-			marginTop: yCorrection,
+			marginLeft: layout.xCorrection,
+			marginTop: layout.yCorrection,
 			overflow: 'hidden',
 		};
-	}, [canvasSize, config]);
+	}, [canvasSize, config, layout, scale]);
 
 	const onError = useCallback(
 		(error: Error) => {
@@ -518,6 +516,7 @@ const PlayerUI: React.ForwardRefRenderFunction<
 					onSeekStart={onSeekStart}
 					inFrame={inFrame}
 					outFrame={outFrame}
+					initiallyShowControls={initiallyShowControls}
 				/>
 			) : null}
 		</>

packages/player/src/player-methods.ts

@@ -17,6 +17,7 @@ export type PlayerMethods = {
 	isPlaying: () => boolean;
 	mute: () => void;
 	unmute: () => void;
+	getScale: () => number;
 };
 
 export type PlayerRef = PlayerEmitter & PlayerMethods;