Configure a single video with data-swarm-setup

data-swarm-setup is an attribute you add to one <smartvideo> tag to change how that player behaves. Everything else on the page keeps your global settings.

Reach for it when one video needs to differ — a testimonial that should loop silently, a training video where the number keys shouldn’t jump around, one video that needs its own promo banner.

For settings that apply site-wide, use swarmoptions instead.

The format

The attribute takes a JSON object. That means double quotes around every property name and every string value, so wrap the attribute itself in single quotes:

<smartvideo src="https://your-video.example.com/file.mp4"
            width="1280" height="720"
            class="swarm-fluid" controls
            data-swarm-setup='{"loop": true, "muted": true}'>
</smartvideo>

This is stricter than the swarmoptions object, which is ordinary JavaScript. In swarmoptions you can write { loop: true }; in data-swarm-setup it has to be {"loop": true}.

Get the JSON right before you publish. If the value isn’t a valid JSON object, SmartVideo ignores the whole attribute, loads the player with your normal settings, and writes a message to the browser console naming the value it rejected. The video still plays and nothing else on the page is affected — but none of your per-video settings apply, and that console message is the only sign. Load the page once with the console open after editing the attribute.

Watch your quotes

The attribute is wrapped in single quotes and the JSON inside it uses double quotes. An apostrophe in your own text ends the attribute early and breaks the tag:

<!-- broken: the apostrophe in "don't" closes the attribute -->
data-swarm-setup='{"plugins": {"overlay": {"overlays": [{"content": "Don't miss out"}]}}}'

<!-- correct: write the apostrophe as &#39; -->
data-swarm-setup='{"plugins": {"overlay": {"overlays": [{"content": "Don&#39;t miss out"}]}}}'

The same applies to any HTML you put in banner content — use ' for apostrophes and keep attribute values inside that HTML in double quotes, which are safe here because JSON already escapes them as \".

What you can set per video

Plugin settings are merged with your global ones rather than replacing them, so naming a single key changes just that key.

What you can’t set per video

Anything else you put in the attribute is passed through to the underlying player untouched. That is not a supported surface — if it isn’t in the table above, we can’t promise it does anything useful, and options that rebuild the player’s controls can break it outright.

Which setting wins

A setting can come from three places. They apply in this order, each layer overriding the one above it:

1. The tag’s HTML attributes — controls, muted, loop, poster on the <smartvideo> tag itself.
2. Your global swarmoptions — the page-wide baseline.
3. This video’s data-swarm-setup — wins over both.

So a tag that carries controls but sets {"controls": false} in data-swarm-setup hides its controls: the attribute is the starting point, the attribute value in the JSON is the last word. data-swarm-setup only overrides the keys you actually name — everything else still comes from your global settings.

autoplay is the one exception to this order, covered next.

Autoplay is the exception

Don’t use data-swarm-setup to switch autoplay on or off. Autoplay is driven by the autoplay attribute on the tag itself, and SmartVideo starts playback from that attribute directly — {"autoplay": false} will not stop a tag that carries it.

To control autoplay, add or remove the attribute:

<!-- autoplays -->
<smartvideo src="https://your-video.example.com/file.mp4"
            width="1280" height="720"
            class="swarm-fluid" controls autoplay muted playsinline>
</smartvideo>

<!-- does not autoplay -->
<smartvideo src="https://your-video.example.com/file.mp4"
            width="1280" height="720"
            class="swarm-fluid" controls>
</smartvideo>

The basic SmartVideo tag options article covers autoplay, muted, loop, and playsinline as tag attributes.

Example: turn off keyboard shortcuts for one video

Useful when a video sits inside an interactive page and the arrow keys should scroll rather than seek.

<smartvideo src="https://your-video.example.com/file.mp4"
            width="1280" height="720"
            class="swarm-fluid" controls
            data-swarm-setup='{"plugins": {"keyboard": {"enabled": false}}}'>
</smartvideo>

Example: loop one video with no controls

<smartvideo src="https://your-video.example.com/file.mp4"
            width="1280" height="720"
            class="swarm-fluid" autoplay muted playsinline
            data-swarm-setup='{"loop": true, "controls": false}'>
</smartvideo>

Autoplay and muting stay on the tag as attributes; looping and the hidden control bar come from data-swarm-setup. Browsers block autoplay with sound, so keep muted set whenever you autoplay.

Example: a promo banner on one video only

Available on the Growth and Pro plans.

<smartvideo src="https://your-video.example.com/file.mp4"
            width="1280" height="720"
            class="swarm-fluid" controls
            data-swarm-setup='{"plugins": {"overlay": {"overlays": [{"content": "Save 20% today", "align": "bottom", "start": 3, "end": 15}]}}}'>
</smartvideo>

Example: watermark one video differently

Available on the Pro plan.

<smartvideo src="https://your-video.example.com/file.mp4"
            width="1280" height="720"
            class="swarm-fluid" controls
            data-swarm-setup='{"plugins": {"watermark": {"file": "https://your-site.example.com/client-logo.png", "xpos": 100, "ypos": 100, "opacity": 50}}}'>
</smartvideo>

When the attribute seems to be ignored

1. Open the browser console. When the attribute is bad, SmartVideo says so and quotes your value back — either data-swarm-setup is not valid JSON; ignoring it or data-swarm-setup must be a JSON object; ignoring it. That message identifies the problem faster than anything else on this list.
2. Paste the attribute value into a JSON validator. Any online JSON linter will do. Worth it when the console has told you the JSON is invalid but a long value makes the reason hard to spot by eye.
3. Check the quoting. Single quotes around the attribute, double quotes inside it. A double-quoted attribute containing double-quoted JSON ends the attribute early, and an apostrophe in your text does the same — write it as '.
4. Check the value is an object. It must start with { and end with }. A JSON array like ["loop"] or a bare string is valid JSON but not a valid setting, so the whole attribute is ignored.
5. Check it belongs here. theme and autoreplace are global-only; move them to swarmoptions.
6. Still stuck? Send us the tag and we’ll tell you what’s wrong with it.

Related articles

• Configure SmartVideo with swarmoptions
• Basic SmartVideo tag options
• Advanced SmartVideo tag options