Willow: the mass documenting

2026-06-20T11:55:00Z

the mass documenting

New page

'''Module:Sound creates a small clickable volume icon that plays an uploaded audio file when clicked.'''
__TOC__

== Overview ==

This module powers {{tl|Sound}}. Given the name of an audio file uploaded to the wiki, it outputs a volume-icon button that the wiki's JavaScript turns into a play control. It does this by resolving the file's URL and storing it on the button as a <code>data-sound-file</code> attribute; a site gadget/script then plays that URL when the icon is clicked. It does not play audio by itself — it only builds the button markup and supplies the file URL.

Editors use the {{tl|Sound}} template rather than calling the module directly.

== Functions / entry points ==

{| class="wikitable"
! Function (#invoke) !! What it does !! Called by
|-
| <code>p.main</code> || Reads the file name (arg 1) and optional icon size (arg 2, default <code>20px</code>) from the parent template, resolves the file's URL via the <code>filepath</code> parser function, and returns a <code><span class="sound-button" data-sound-file="..."></code> containing a <code>File:Icon-Volume.png</code> image. Returns a red error message if no file name is given. || {{tl|Sound}}
|}

== How it's used ==

{{tl|Sound}} is simply:

<pre>
<includeonly>{{#invoke:Sound|main}}</includeonly>
</pre>

So on a page an editor writes, for example:

<pre>
{{Sound|MyBossRoar.ogg}}
{{Sound|MyBossRoar.ogg|32px}}
</pre>

* '''Argument 1''' — the audio file name as uploaded (e.g. <code>MyBossRoar.ogg</code>). Read from the parent template's parameters.
* '''Argument 2''' (optional) — the size of the volume icon, default <code>20px</code>.

Editors should use {{tl|Sound}}; the raw <code>{{#invoke:Sound|main}}</code> only appears inside that template.

== Notes ==

* The play behaviour depends on an external site script/gadget that reads <code>data-sound-file</code> and the <code>sound-button</code> class. The module only emits the markup and the resolved URL; if that script isn't loaded, clicking does nothing.
* The file URL comes from <code>{{filepath:...}}</code>. Protocol-relative URLs (starting <code>//</code>) are prefixed with <code>https:</code>.
* The clickable icon is <code>File:Icon-Volume.png</code>, rendered with <code>link=</code> (no link target) so the click is handled by the script, not by following a link.
* Newlines/carriage returns are stripped from the output so it can be used inline.
* '''Related:''' {{tl|Sound}}.

Module:Sound/doc - Revision history

Willow: the mass documenting