APlayer & MetingJS Integration#

Overview#

Butterfly embeds APlayer (a web audio player) via MetingJS, a wrapper that translates HTML data-* attributes into API calls against streaming music platforms (NetEase, Tencent, Kugou, etc.). The theme ships APlayer v1.10.1 and MetingJS v1.1.6 (from the butterfly-extsrc package) as optional built-in dependencies — no separate Hexo plugin is required.

Key entry points:

• Template: layout/includes/third-party/aplayer.pug
• Injection gate: layout/includes/additional-js.pug
• Default config: scripts/common/default_config.js
• Asset version pins: plugins.yml

Enabling the Integration#

The feature is gated by aplayerInject in _config.yml 1:

aplayerInject:
  enable: false # master switch (off by default)
  per_page: true # inject scripts on every page

aplayer.pug is only included when enable: true and at least one of 2:

• per_page: true
• PJAX is globally enabled (theme.pjax.enable)
• The current page sets aplayer: true in its front-matter

hexo-tag-aplayer conflict: If the hexo-tag-aplayer Hexo plugin is installed, set asset_inject: false in Hexo's root _config.yml to prevent double-injecting APlayer/MetingJS assets. 3

Asset Loading#

aplayer.pug injects three assets in order: CSS → APlayer JS → MetingJS.

4 5

The CSS link uses media="print" + onload="this.media='all'" for non-render-blocking load 6. CDN source and custom URLs for all three assets can be overridden under CDN.option (keys: aplayer_css, aplayer_js, meting_js).

MetingJS version note: The bundled version is v1.1.6 (not v2.x) to preserve compatibility with hexo-tag-aplayer. 3

Placing a Player#

Global sticky player via inject.bottom#

Insert the APlayer HTML div into inject.bottom:

inject:
  bottom:
    - <div class="aplayer no-destroy" data-id="60198" data-server="netease"
        data-type="playlist" data-fixed="true" data-autoplay="true"></div>

Raw HTML with data-* attributes is sufficient — hexo-tag-aplayer is not needed. 3

MetingJS data attributes#

3

Per-page player via front-matter#

To scope APlayer injection to a single post without enabling per_page site-wide, add to the post's front-matter:

aplayer: true

Then write the <div class="aplayer" ...> inline in the Markdown body. The injection gate checks page.aplayer as a third path 2.

PJAX Lifecycle Hooks#

When PJAX is enabled, aplayer.pug registers two hooks via btf.addGlobalFn:

7

destroyAplayer iterates window.aplayers and skips any instance where options.fixed === true 8. A global sticky player with data-fixed="true" therefore survives page transitions uninterrupted. The no-destroy CSS class seen in tutorials is a naming convention only — the real guard is the fixed APlayer option.