Media Players

Xingluo integrates APlayer (audio) and DPlayer (video), supporting two ways to create players in Markdown and MDX, all lazy-loaded.

Enabling

Toggle each player as needed in features.players in xingluo.config.ts:

ts
features: {
  players: {
    aplayer: true,  // Enable APlayer audio player
    dplayer: true,  // Enable DPlayer video player
  },
}

The two are independent. When disabled:

• The remarkPlayers plugin is not injected (MD fences are not parsed)
• The player client script is not loaded
• The build output has no aplayer / dplayer chunks

Two Usage Modes

Both modes ultimately output the same placeholder div structure (<div class="xng-aplayer|xng-dplayer" data-config>), lazy-loaded and instantiated by src/scripts/players.ts.

APlayer Audio Player

MD Fence

markdown
```aplayer
{
  "audio": [
    {
      "name": "Song",
      "artist": "Artist",
      "url": "/audio/song.mp3",
      "cover": "/images/cover.jpg",
      "lrc": "[00:00.00] First lyric line"
    }
  ],
  "theme": "#b7daff",
  "loop": "all",
  "autoplay": false
}
```

MDX Component

mdx
import { APlayer } from "@/components/mdx";

<APlayer
  audio={[
    {
      name: "Song",
      artist: "Artist",
      url: "/audio/song.mp3",
      cover: "/images/cover.jpg",
    },
  ]}
  theme="#b7daff"
  loop="all"
/>

Options

audio Object

DPlayer Video Player

MD Fence

markdown
```dplayer
{
  "video": {
    "url": "/videos/demo.mp4",
    "pic": "/images/video-cover.jpg",
    "type": "auto"
  },
  "theme": "#b7daff",
  "autoplay": false,
  "loop": false
}
```

MDX Component

mdx
import { DPlayer } from "@/components/mdx";

<DPlayer
  video={{ url: "/videos/demo.mp4", pic: "/images/video-cover.jpg" }}
  theme="#b7daff"
  subtitle={{ url: "/subtitles.vtt", type: "webvtt" }}
/>

Options

video Object

subtitle Object

danmaku Object

Lazy Loading Mechanism

Players are lazy-loaded via IntersectionObserver: the placeholder div dynamically imports the player module and styles and instantiates only when within 200px of the viewport.

• APlayer: dynamic import("aplayer") + import("aplayer/dist/APlayer.min.css")
• DPlayer: dynamic import("dplayer") (styles are inlined in JS; no separate CSS needed)

Module loading uses a shared Promise cache to avoid repeated dynamic imports. Re-instantiation is prevented via dataset markers (xng-init, xng-observed).

View Transitions Adaptation

The player script listens for astro:page-load and re-scans placeholder divs after each page load. After a View Transitions page switch, the new page’s player placeholders are re-observed and lazy-loaded.

Performance

• Zero bundle when players are disabled (remark plugin not injected, client script not loaded)
• Zero runtime when enabled but no players on a page (script loads but does not instantiate)
• Player modules are standalone chunks, loaded on demand only on pages that use them
• CSS and JS are imported separately to ensure styles are ready before instantiation

Type Declarations

APlayer and DPlayer have no official TypeScript types; Xingluo provides loose module declarations in src/types/aplayer.d.ts and src/types/dplayer.d.ts, with options fields set optional for spread compatibility. MDX component Props have full type constraints.