# VideoPlayer
Loop short clips while keeping native controls for longer videos.
import { VideoPlayer } from '@prosefly/astro-components';
`VideoPlayer` enhances the native `video` element without replacing its full
control bar. By default, clips up to **30 seconds** loop silently while visible;
longer videos stay manual and use the browser's playback controls.
## Short Clip
```mdx
import { VideoPlayer } from '@prosefly/astro-components';
```
Short clips have white circular Lucide play/pause and sound buttons when the
browser can determine whether an audio track exists. The buttons appear on
hover, keyboard focus, or pause, and stay visible on touch devices.
Confirmed silent clips omit the sound button. Unknown audio falls back to
native controls; zero decoded audio bytes alone never counts as proof of silence.
Looping pauses when a clip leaves the viewport or the tab becomes hidden, and
resumes silently when it becomes visible again. A manual pause stays paused.
With reduced motion enabled, playback requires an explicit user action.
If autoplay is blocked, the play control remains available.
## Native Controls
Set `shortVideoSeconds={0}` to disable automatic looping, even for short clips:
```mdx
```
Videos longer than the threshold, streams, and videos with unknown duration
also use native controls. They do not autoplay. Videos containing `track`
children retain native controls so captions can still be selected. Without
JavaScript, the original video and native controls remain usable.
## Automatic Markdown And MDX Figures
Figure conversion is enabled by default. Register the shared integration once
in a standalone Astro project:
```ts title="astro.config.ts"
import mdx from '@astrojs/mdx';
import { defineConfig } from 'astro/config';
import proseflyComponents from '@prosefly/astro-components/integration';
export default defineConfig({
integrations: [
proseflyComponents(),
mdx(),
],
});
```
Authors can then write ordinary HTML in `.md` and `.mdx` files without importing a component.
The `mdx()` integration is only needed for `.mdx` files:
A short clip, authored as an HTML figure.
```mdx
A short demo with a guide.
```
`rehypeVideoPlayer` generates HTML directly, preserving figure and video
attributes (including MDX expressions and spreads), multiple sources, tracks,
and the original rich `figcaption`. The integration loads the shared styles and
browser runtime. Image figures, audio figures, figures with additional content,
multiple videos, or no source are left alone. Standalone `video` elements are
not transformed.
`data-duration` is an optional hint in seconds; actual browser metadata takes
precedence. No videos are fetched during compilation, and no URL-specific
audio lookup is used. At runtime the player manages `controls`, `loop`,
`autoplay`, and mute state according to its playback policy.
To disable figure conversion, use
`proseflyComponents({ markdown: { videoPlayer: false } })`.
For custom thresholds or translations, pass an options object:
```ts
proseflyComponents({
markdown: {
videoPlayer: {
shortVideoSeconds: 15,
labels: { play: '再生', pause: '一時停止', mute: '消音', unmute: '音声をオン' },
},
},
});
```
### Independent Plugin And Themes
Lotus and Dahlia already register the shared integration and enable figure
conversion; no additional plugin is needed. For custom thresholds, translations,
or disabling conversion, register your configured integration before the theme.
The theme will reuse it instead of registering another instance:
```ts title="astro.config.ts"
import { defineConfig } from 'astro/config';
import lotus from '@prosefly/astro-theme-lotus';
import proseflyComponents from '@prosefly/astro-components/integration';
export default defineConfig({
integrations: [
proseflyComponents({
markdown: { videoPlayer: { shortVideoSeconds: 15 } },
}),
lotus(),
],
});
```
The `/markdown` entry exports `rehypeVideoPlayer` and `VideoPlayerOptions` for
processor composition. Use `proseflyComponents()` to load the player styles
and browser runtime.
## Sources And Captions
For direct component use, put `source` children inside `VideoPlayer` and use the
`caption` prop for plain text:
```mdx
```
For tracks, custom fallback content, figure attributes, or rich captions, write
an ordinary `` with a `