# Shopify
> Add WaveformPlayer to a Shopify theme.
WaveformPlayer is a single CSS file and a single browser-global script — no build step, no bundler. That makes it a natural fit for Shopify themes, where you drop the assets into your theme, then render players declaratively with `data-*` attributes generated by Liquid (a product audio file, a metafield, a section setting, and so on).
This page covers both hosting options (theme `assets/` or CDN), the Liquid markup contract, a reusable snippet, a full section with schema settings, and the Theme Editor lifecycle hooks you need so players keep working when merchants add or remove sections live.
## How it loads
The IIFE build (`dist/waveform-player.min.js`) exposes a `window.WaveformPlayer` global and **auto-initialises on `DOMContentLoaded`**: it scans the DOM for any element carrying `data-waveform-player` and instantiates a player for it. You never have to write JavaScript for the common case — emit the right markup from Liquid and the script does the rest.
`WaveformPlayer.init()` is idempotent (it marks each element with `data-waveform-initialized="true"` and skips already-initialised nodes), which matters for Shopify's Theme Editor — see [Theme Editor lifecycle](#theme-editor-lifecycle).
## 1. Add the assets
You have two options. Self-hosting in the theme's `assets/` folder is recommended for production (one origin, no third-party dependency, served from Shopify's CDN). A public CDN is fine for a quick prototype.
### Option A — self-host in `assets/`
1. Get the two dist files. Install the package and copy them out, or download them from a CDN.
```bash
npm install @arraypress/waveform-player
```
```bash
pnpm add @arraypress/waveform-player
```
```bash
yarn add @arraypress/waveform-player
```
```bash
bun add @arraypress/waveform-player
```
You need exactly two files from `node_modules/@arraypress/waveform-player/dist/`:
- `waveform-player.min.js`
- `waveform-player.css`
2. Upload both to your theme's **Assets** (Online Store → Themes → ⋯ → Edit code → Assets → Add a new asset), or via the Shopify CLI / GitHub integration. Shopify's `assets/` folder is **flat** — no subfolders — so they live as `assets/waveform-player.min.js` and `assets/waveform-player.css`.
3. Reference them in `layout/theme.liquid`, inside `` for the stylesheet and before `` for the script.
```liquid
{{ 'waveform-player.css' | asset_url | stylesheet_tag }}
```
The `asset_url` filter rewrites the filename to the theme's CDN URL, and `stylesheet_tag` emits a proper ``. `defer` lets the script load without blocking render; auto-init still fires on `DOMContentLoaded`.
:::tip[Load only where needed]
If audio appears on a handful of templates, skip `theme.liquid` and load the assets from the section that needs them instead (see [section example](#full-section)). Shopify dedupes identical asset URLs, so referencing the same file from several sections on one page is safe.
:::
### Option B — CDN
For prototypes or themes where you would rather not manage asset files, point at jsDelivr or unpkg. Pin a major version (`@1`) so you get patches without surprise breakage.
```liquid
{# jsDelivr #}
```
```liquid
{# unpkg (the package's "unpkg" entry resolves to the min build) #}
```
## 2. The markup contract
A player is any element with `data-waveform-player` plus a source. Every constructor option has a `data-*` equivalent, parsed by the library at init — so a fully-configured player is pure markup. The minimum is a source URL:
```liquid
```
`data-src` is an alias for `data-url`; if both are present, `data-url` (canonical) wins. The full list of attributes is on the [Data attributes](/player/data-attributes/) page; the most useful ones for theme work:
| Attribute | Maps to | Notes |
| --- | --- | --- |
| `data-src` / `data-url` | `url` | Audio file URL. `data-url` wins if both set. |
| `data-title` | `title` | Falls back to the URL filename if omitted. |
| `data-artist` | `artist` | Second info line (e.g. artist). |
| `data-artwork` | `artwork` | 40×40 thumbnail + Media Session art. |
| `data-waveform-style` / `data-style` | `waveformStyle` | `bars` · `mirror` · `line` · `blocks` · `dots` · `seekbar`. |
| `data-height` | `height` | Waveform height in px (default `64`). |
| `data-waveform-color` | `waveformColor` | CSS colour, or a JSON array of gradient stops. |
| `data-progress-color` | `progressColor` | Played-through colour (or JSON gradient array). |
| `data-color-preset` | `colorPreset` | `dark` / `light`; omit to auto-detect the theme. |
| `data-waveform` | `waveform` | Pre-computed peaks (CSV / JSON array / `.json` URL) to skip Web Audio decode. |
| `data-show-bpm` | `showBPM` | Boolean string `"true"`. |
| `data-bpm` | `bpm` | Known BPM; wins over auto-detection. |
| `data-autoplay` | `autoplay` | Boolean string `"true"`. |
| `data-layout` | `layout` | `default` or `preview`. |
:::note[Booleans are strings]
Liquid renders everything as text, which is exactly what the parser expects. Booleans must be the literal string `"true"` (e.g. `data-show-bpm="true"`). Any other value — including an empty attribute — is treated as not set.
:::
:::caution[Escape dynamic strings]
When you interpolate merchant- or customer-controlled text (a title, artist, or a metafield), pass it through Liquid's `escape` filter so quotes and angle brackets can't break out of the attribute: `data-title="{{ block.settings.title | escape }}"`.
:::
## 3. Drive it from Liquid
The source is usually not a hard-coded asset. Common Shopify patterns:
```liquid
{# A) A file uploaded to Settings → Files, referenced by name #}
{# B) A product metafield holding the audio file (file_reference type) #}
{%- assign audio = product.metafields.custom.audio_file -%}
{%- if audio != blank -%}
{%- endif -%}
{# C) A URL/text metafield (just output the value) #}
```
:::tip[Skip the decode with pre-computed peaks]
Decoding audio in the browser to build the waveform costs a download and CPU. If you precompute peaks and upload a sibling `.json` file (same base name as the audio), point `data-waveform` at it to skip Web Audio entirely:
```liquid
```
The JSON may be a bare peaks array or an object with `peaks` and embedded `markers`. See [Waveform data](/player/waveform-data/).
:::
### Looping a collection
Render a player per product in a collection (or per line item in a cart), guarding on the metafield so products without audio are skipped:
```liquid
{%- for product in collection.products -%}
{%- assign audio = product.metafields.custom.audio_file -%}
{%- if audio != blank -%}
{%- endif -%}
{%- endfor -%}
```
By default each player pauses every other instance when it starts (`singlePlay`, on by default), so a grid behaves like one playlist — only one track plays at a time. Set `data-single-play="false"` on a player to opt it out.
## Reusable snippet
Extract the markup into `snippets/waveform-player.liquid` so templates stay clean. Render it with named parameters:
```liquid
{% comment %} snippets/waveform-player.liquid
Renders a WaveformPlayer. Required: url. Optional: title, artist,
artwork, style, peaks (a .json peaks URL), bpm.
{% endcomment %}
{%- if url != blank -%}
{%- endif -%}
```
Call it from a product template:
```liquid
{% render 'waveform-player',
url: product.metafields.custom.audio_file | file_url,
title: product.title,
artist: product.vendor,
artwork: product.featured_image | image_url: width: 80,
style: 'mirror' %}
```
## Full section
A self-contained section with schema settings lets merchants drop a player onto any page from the Theme Editor and configure it visually. Save as `sections/audio-player.liquid`.
```liquid
{%- comment -%} sections/audio-player.liquid {%- endcomment -%}
{{ 'waveform-player.css' | asset_url | stylesheet_tag }}