swarmoptions is the settings object every SmartVideo player on the page reads. It is where you set your Swarm CDN Key, choose which videos SmartVideo takes over, and style the player to match your brand.

It applies to the page it is on. Because the snippet normally lives in a shared site template or theme header, that usually means every page of your site — but if you paste it into a single page, only that page is affected.

You don’t have to write this by hand. The Configuration tab in your dashboard generates the snippet for you from a set of toggles and color pickers. This article is the reference for what those settings produce, so you can read the generated code, extend it with options the configurator doesn’t cover, or write it yourself.

If you only want to change one video, use the data-swarm-setup attribute instead.

On this page

Where swarmoptions goes
Account options — your key and iframe handling
Choose which videos SmartVideo takes over — autoreplace
Style the player — theme
Keyboard shortcuts
Add a brand watermark
Add a promo banner
Run video ads
When an option doesn’t take effect

Where swarmoptions goes

Declare it in your site’s <head>, above the loader script:

<script data-cfasync="false">
    var swarmoptions = {
        swarmcdnkey: "YOUR_SWARM_CDN_KEY",
        iframeReplacement: "iframe",
        autoreplace: {
        }
    };
</script>
<script async data-cfasync="false" src="https://assets.swarmcdn.com/swarmcdn.js"></script>

Replace YOUR_SWARM_CDN_KEY with the key from your dashboard Configuration tab.

Keep data-cfasync="false" on both tags. It tells Cloudflare’s Rocket Loader to leave them alone, which has broken playback on customer sites in the past.

If you are installing SmartVideo for the first time, start with the installation guide for your platform — this article is the reference for what you can put inside the object once it is there.

How the options are organized

Options live in four groups. swarmcdnkey is the only one you always need — the rest are optional, though a feature you do turn on may have required fields of its own (a watermark needs a file, for example).

<script data-cfasync="false">
    var swarmoptions = {
        swarmcdnkey: "YOUR_SWARM_CDN_KEY",   // your account key
        autoreplace: { },                    // which videos SmartVideo takes over
        theme: { },                          // how the player looks
        plugins: { }                         // keyboard, watermark, banners, ads
    };
</script>

Option names are case-sensitive. primaryColor works; primarycolor is ignored.

Account options

Option	Type	Default	What it does
`swarmcdnkey`	string	—	Your Swarm CDN Key. Required — without it the player never starts.
`iframeReplacement`	`"video"` or `"iframe"`	`"video"`	How a replaced YouTube embed is rebuilt. `"video"` swaps in a real SmartVideo player. `"iframe"` keeps an iframe wrapper, which some page builders need.

Choose which videos SmartVideo takes over

These live under autoreplace.

Option	Type	Default	What it does
`smartvideotag`	boolean	`true`	Scan the page for `<smartvideo>` tags. On unless you turn it off.
`youtube`	boolean	`false`	Replace YouTube embeds with an accelerated player. Currently paused — see the note below.
`vimeo`	boolean	`false`	Replace Vimeo embeds.
`youtubecaptions`	boolean	`false`	Pull the caption track across from YouTube. Currently paused — see the note below.
`videotag`	boolean	`false`	Accelerate plain `<video>` tags — this is how you speed up background and hero videos.
`vimeoIframeReplacement`	`"video"` or `"iframe"`	`"video"`	The Vimeo equivalent of `iframeReplacement`.

Accelerating plain <video> tags with videotag is available on the Growth and Pro plans. See plans and pricing.

Note on YouTube: Auto-conversion from YouTube is currently paused, so youtube and youtubecaptions have no effect today. We’re exploring an importer-style replacement inside the SmartVideo library, but have no timeline to share. For now, download the YouTube video and upload it to SmartVideo storage through your SmartVideo dashboard. See Can I use YouTube videos? for the full picture.

<script data-cfasync="false">
    var swarmoptions = {
        swarmcdnkey: "YOUR_SWARM_CDN_KEY",
        autoreplace: {
            vimeo: true,
        }
    };
</script>

Style the player

These live under theme and apply to every player on the page.

Option	Type	Default	What it does
`primaryColor`	any CSS color	player default	Accent color: play button, progress bar, active controls. See customize player color.
`secondaryColor`	any CSS color	player default	Companion color used against the primary.
`glassTint`	whole number 0–15	`3`	How much of your `primaryColor` is mixed into the frosted-glass control bar. `0` leaves it neutral, `15` is the strongest tint. Because it tints toward your own color, a light `primaryColor` makes the bar lighter, not darker.
`cornerRadius`	CSS length	player default	Rounds the corners of the player itself, e.g. `"24px"` or `"0px"`.
`button`	string or object	`"hexagon"`	Play button shape. See customize play button shape.
`button.shape`	`"hexagon"`, `"rectangle"`, or `"circle"`	`"hexagon"`	Shape, when you pass an object.
`button.borderRadius`	CSS length	`16px` for hexagon and circle, `4px` for rectangle	Rounds the button’s own corners.

button accepts a bare shape name (button: "circle") when you don’t need to set the radius.

<script data-cfasync="false">
    var swarmoptions = {
        swarmcdnkey: "YOUR_SWARM_CDN_KEY",
        theme: {
            primaryColor: "#ffde17",
            glassTint: 3,
            cornerRadius: "24px",
            button: {
                shape: "hexagon",
                borderRadius: "16px"
            }
        }
    };
</script>

A glassTint outside 0–15 is pulled back to the nearest end of the range, and an unrecognized shape falls back to hexagon. Both write a warning to your browser console rather than failing.

Keyboard shortcuts

Keyboard shortcuts are on by default — you only need plugins.keyboard to change or disable them.

Option	Type	Default	What it does
`enabled`	boolean	`true`	Set to `false` to turn all shortcuts off.
`seekStep`	seconds	`5`	How far the left and right arrow keys jump.
`seekStepLarge`	seconds	`10`	How far the J and L keys jump.
`volumeStep`	0–1	`0.05`	Volume change per up/down arrow press.
`frameStep`	seconds	`0.04`	Frame-step size, roughly one frame at 25fps.
`enableMute`	boolean	`true`	The M key.
`enableFullscreen`	boolean	`true`	The F key.
`enableNumbers`	boolean	`true`	Keys 0–9 jump to that percentage of the video.
`enableCaptions`	boolean	`true`	The C key.
`restoreFocus`	boolean	`true`	Return keyboard focus to the player after a control is clicked.

<script data-cfasync="false">
    var swarmoptions = {
        swarmcdnkey: "YOUR_SWARM_CDN_KEY",
        plugins: {
            keyboard: {
                seekStep: 10,
                enableNumbers: false
            }
        }
    };
</script>

To switch shortcuts off entirely:

plugins: {
    keyboard: { enabled: false }
}

Add a brand watermark

Available on the Pro plan. See plans and pricing.

plugins.watermark puts your logo over every player.

Option	Type	Default	What it does
`file`	image URL	—	Required. The logo to display. Nothing renders without it.
`xpos`	`0`, `50`, or `100`	`0`	Horizontal position: `0` left, `50` center, `100` right.
`ypos`	`0`, `50`, or `100`	`0`	Vertical position: `0` top, `50` middle, `100` bottom.
`opacity`	0–100, or 0–1	`100`	How solid the logo is. Both scales are accepted.

The two values combine into nine positions:

	`xpos: 0`	`xpos: 50`	`xpos: 100`
`ypos: 0`	top-left	top	top-right
`ypos: 50`	left	center	right
`ypos: 100`	bottom-left	bottom	bottom-right

<script data-cfasync="false">
    var swarmoptions = {
        swarmcdnkey: "YOUR_SWARM_CDN_KEY",
        plugins: {
            watermark: {
                file: "https://your-site.example.com/logo.png",
                xpos: 100,
                ypos: 0,
                opacity: 75
            }
        }
    };
</script>

The watermark appears over the poster image before playback starts and stays for the whole video.

Available on the Growth and Pro plans. See plans and pricing.

plugins.overlay shows timed HTML over the player — a discount, a link, a call to action. Each entry in overlays is one banner.

Option	Type	What it does
`content`	HTML string	What the banner shows.
`align`	`top`, `bottom`, `top-left`, `top-right`, `bottom-left`, `bottom-right`, `center`	Where it sits.
`start`	seconds, or `"play"`	When it appears.
`end`	seconds	When it disappears. Leave it out to keep the banner up.

<script data-cfasync="false">
    var swarmoptions = {
        swarmcdnkey: "YOUR_SWARM_CDN_KEY",
        plugins: {
            overlay: {
                overlays: [
                    {
                        content: "<a href='https://your-site.example.com/sale'>Limited time: 20% off</a>",
                        align: "bottom",
                        start: 3,
                        end: 15
                    }
                ]
            }
        }
    };
</script>

content is raw HTML, so mind your quotes: the example uses single quotes for the link’s href because the whole string is already wrapped in double quotes. If your banner text contains an apostrophe, that is fine here — but see the per-video article before copying banner HTML into a data-swarm-setup attribute, where apostrophes need more care.

Watermarks and banners share one overlay layer, so you can use both at once.

Run video ads

Available on the Pro plan. See plans and pricing.

plugins.swarmads takes a VAST or VPAID tag URL. Setup and ad-network specifics are covered in ad network integration.

plugins: {
    swarmads: {
        adTagUrl: "https://your-ad-server.example.com/vast.xml"
    }
}

Worked example: brand the player and accelerate everything

<script data-cfasync="false">
    var swarmoptions = {
        swarmcdnkey: "YOUR_SWARM_CDN_KEY",
        iframeReplacement: "iframe",
        autoreplace: {
            vimeo: true,
            videotag: true
        },
        theme: {
            primaryColor: "#e63946",
            secondaryColor: "#3a0e11",
            glassTint: 12,
            cornerRadius: "0px",
            button: {
                shape: "circle"
            }
        },
        plugins: {
            watermark: {
                file: "https://your-site.example.com/logo.png",
                xpos: 100,
                ypos: 0,
                opacity: 60
            }
        }
    };
</script>
<script async data-cfasync="false" src="https://assets.swarmcdn.com/swarmcdn.js"></script>

When an option doesn’t take effect

Check your browser console. Invalid values warn by name and fall back to the default rather than breaking the player. To open it, press F12 (Command-Option-I on a Mac) and choose the Console tab. If a message mentions SmartVideo and you’re not sure what it means, send it to us and we’ll read it for you.
Check the nesting. glassTint belongs inside theme, not at the top level. seekStep belongs inside plugins.keyboard.
Check the capitalization. Option names are case-sensitive, and the object itself is all lowercase: swarmoptions, not swarmOptions.
Check that the key is set. Without a valid swarmcdnkey the player never starts, so no other option applies.

Configure SmartVideo with swarmoptions

Where swarmoptions goes

How the options are organized

Account options

Choose which videos SmartVideo takes over

Style the player

Keyboard shortcuts

Add a brand watermark

Run video ads

Worked example: brand the player and accelerate everything

When an option doesn’t take effect

Get SmartVideo live on your site

Configure SmartVideo with swarmoptions

Where swarmoptions goes

How the options are organized

Account options

Choose which videos SmartVideo takes over

Style the player

Keyboard shortcuts

Add a brand watermark

Add a promo banner

Run video ads

Worked example: brand the player and accelerate everything

When an option doesn’t take effect

Related articles

Related articles

Get SmartVideo live on your site