Sirv Media Viewer

Note: This documentation is being updated daily, prior to the official launch of Sirv Media Viewer in Q1 2019. If you need help customizing Sirv Media viewer, please contact us.

About

Sirv Media Viewer is a unified viewer for displaying all types of image, 360 spin and video. It can be customized in many ways to suit your website.

This is the default look & feel:

Embed images

It’s easy to embed Sirv Media viewer in your page.

1. Copy and paste this script anywhere in your HTML (usually before the </head> or before the </body>):

<script src="https://scripts.sirv.com/smv/v3/b3/sirv.js"></script>

2. Add a div with class of “Sirv”, containing each of your assets. Each image or spin should be in a div and each video should be in an iframe. This example contains one spin, one zoomable image and one video:

<div class="Sirv">
    <div data-src="https://demo.sirv.com/example.spin"></div>
    <div data-src="https://demo.sirv.com/example1.jpg" data-effect="zoom"></div>
    <iframe data-src="https://www.youtube.com/watch?v=svK_DnHu-7I" style="width:100%; height:100%" frameborder="0" allow="encrypted-media" allowfullscreen></iframe>
</div>

Viewer options

Parameter Default Options Description
orientation horizontal horizontal, vertical Layout of thumbnails.
arrows true true, false Display arrows to the left/right of the image.
loop true true, false Loop from the last image to the first image.
autostart visible visible, created, off When to load images.
Slider
slide.first 0 numeric First slide to play (from 0 upwards).
slide.delay 3000 numeric Time between each autoslide (ms).
slide.preload true true, false Preload the images, to remove any loading delay.
slide.autoplay false true, false Automatically slide the images in a slideshow.
slide.animation.type fade fade, slide, off Style of animation.
slide.animation.duration 200 numeric Duration of animation effect (ms).
Video
video.autoplay true true, false Enable autoplay of video.
Thumbnails
thumbnails.enable true true, false Display thumbnail for each item.
thumbnails.position bottom bottom, top, left, right Thumbnail location, relative to main image.
thumbnails.type square square, auto, bullets Style of thumbnails.
thumbnails.size 70 numeric Thumbnail height/width (px).
thumbnails.target false true, false
Fullscreen
fullscreen.enable true true, false Enable option to go fullscreen.
fullscreen.always false true, false Go immediately to fullscreen on click.
fullscreen.native false true, false Use entire fullscreen instead of page fullscreen.
fullscreen.thumbnails.enable true true, false Show thumbnails in fullscreen mode.
fullscreen.thumbnails.type square square, auto, bullets Style of fullscreen buttons.
fullscreen.thumbnails.size auto auto or number (px) Dimensions of fullscreen thumbnails.
fullscreen.thumbnails.position bottom bottom, top, left, right Location of fullscreen thumbnails.
fullscreen.thumbnails.autohide false true, false Hide the thumbnails discreetly.
Context menu
contextmenu.enable false true, false Enable the context menu on right-click.

Spin options

Parameter Default Options Description
swapSides false true, false
wheel false true, false Rotate spin with mousewheel.
initialize load load, hover, click Initiate image downloading.
inactivity 3000 numeric (ms) Wait time before spin considered inactive.
column.start 1 Frame number of first image shown on load.
column.loop true true, false Loop between first and last frame.
column.increment 1 numeric Number of frames to jump when spinning.
column.reverse false true, false Change direction of spin.
column.sensitivity 50 1-100 Speed of spin when dragging.
row.start 1 Number of first frame to show after load.
row.loop false true, false Loop after last frame to next row.
row.increment 1 numeric Number of frames to jump when spinning.
row.reverse false true, false Change direction of spin.
row.sensitivity 50 1-100 Speed of spin when dragging.
Autospin
autospin.enable false true, false Continuously rotate the spin.
autospin.type sphere sphere, row, full, helix Style of autospin animation, for multi-row spins.
autospin.duration 3600 numeric (ms) Time to complete 1 full rotation.
Zoom
zoom.enable true true, false Allow zoom into image.
zoom.ratio 2.5 multiple Magnification level.
zoom.tiles true true, false Break zoomed image into tiles.
zoom.pan true true, false Pan the zoomed image on hover.
Hint
hint.message.enable true true, false Show hint that image is interactive.
hint.message.text Drag to spin Text displayed in hint.
hint.onStart.enable true true, false Show hint once images have loaded.
hint.onStart.effect intro intro, twitch, spin, momentum, sphere, none Style of animation.
hint.onVisible.enable true true, false Show hint when spin becomes visible.
hint.onVisible.effect intro intro, twitch, spin, momentum, sphere, none Style of animation.
hint.onActive.enable true true, false Show hint after period of inactivity.
hint.onInactive.effect intro intro, twitch, spin, momentum, sphere, none Style of animation.

Zoom options

Parameter Default Options Description
mode inner inner, top, left, right, bottom, magnifier, deep Method for zooming an image.
margin 9 numeric (px) Padding between main image and zoomed image.
width auto auto / numeric (px) Width of image.
height auto auto / numeric (px) Height of image.
pan false true, false Pan the image on hover.
ratio 2.5 numeric Magnification level between each zoom.
wheel true true, false Zoom in/out on mousewheel.
tiles true true, false Zoom with small, 256px tiled images.
trigger dblclick dblclick / hover / click Method to trigger zoom.
Hint
hint.enable true true, false Hint that image is zoomable.
hint.text.hover Hover to zoom Text shown if trigger is hover.
hint.text.click Click to zoom Text shown if trigger is click.
hint.text.dblclick Double click to zoom Text shown if trigger is double-click.
hint.map.enable false true, false Display location map in corner.
hint.map.size 25 Percentage Size of map in relation to main image.

Responsive image options

Parameter Default Options Description
image.lazy true true, false Lazy loading, load image as they enter viewport.
image.loadLowQualityImage false true, false Load tiny (low quality) image first.
image.resize true true, false Resize image to perfect width/height.
image.threshold 0 number (px) Distance from viewport before loading is triggered.

Ways to apply options

Options can be applied either to each image individually in the div or to all instances on the page in a script.

Options applied to a div via the data-options tag can be either in the viewer div or the image/spin/video div:

<div class="Sirv" data-options="fullscreen.enable:false;">
    <div data-src="https://demo.sirv.com/example.spin" data-effect="zoom" data-options="inactivity:7000;"></div>
    <div data-src="https://demo.sirv.com/example.jpg" data-effect="zoom" data-options="mode:right;"></div>
    <div data-src="https://demo.sirv.com/example.jpg" data-options="loadLowQualityImage:true;"></div>
</div>

Options applied with a script:

<script>
    var SirvOptions = {
        zoom: {
            mode: 'right',
            }
        }
</script>

Mobile settings

To set different settings for mobile devices, use one of three ways to apply options. The examples below change the spin hint message to “Tap then drag”.

Use a script to apply the settings to all instances on a page:

<script>
var SirvMobileOptions = {
    spin: {
        hint: {
            message: {
                text: 'Tap then drag'
            }
        }
    }
};
</script>

Alternatively, apply inline settings to Sirv Media Viewer:

<div class="Sirv" data-mobile-options="spin.hint.message.text: Tap then drag">

Or apply inline settings to a specific item inside the viewer:

<div class="Sirv">
    <div data-src="https://demo.sirv.com/example.spin" data-mobile-options="hint.message.text: Tap then drag"></div>
</div>

Image zoom

There are many different image zoom effects to choose from.

Inner zoom

The default zoom effect is internal zoom:

<div class="Sirv">
    <div data-effect="zoom" data-src="https://demo.sirv.com/trainer.jpg" data-options="mode:inner"></div>
</div>

A magnifying glass can be used, by setting mode to magnifier:

<div class="Sirv">
    <div data-effect="zoom" data-src="https://demo.sirv.com/trainer.jpg" data-options="mode:magnifier"></div>
</div>


A multi-level zoom is ideal for zooming deep into huge images. Set mode to deep:

<div class="Sirv">
    <div data-effect="zoom" data-src="https://demo.sirv.com/trainer.jpg" data-options="mode:deep"></div>
</div>

Multi-level zoom can be zoomed on single click (instead of double-click) by setting trigger to click:

<div class="Sirv">
    <div data-effect="zoom" data-src="https://demo.sirv.com/trainer.jpg" data-options="mode:deep; trigger:click"></div>
</div>

A hover zoom can shown to the right (default), left, top or bottom of the main image. Set mode to right/left/top/bottom:

<div class="Sirv">
    <div data-effect="zoom" data-src="https://demo.sirv.com/trainer.jpg" data-options="mode:right"></div>
</div>

If there is insufficient space for the zoomed image, internal zoom will be used instead.

Spin thumbnail design

The background color and opacity of thumbnail overlays can be controlled with CSS. This CSS would apply a mid grey color, with 56% opacity:

<style>
.smv-thumbnails .smv-selector[data-type="spin"]:before {
    background-color: rgba(128, 128, 128, 0.56);
}
</style>

The 360 spin thumbnail can use any SVG or PNG image of your own design. Sirv provides a range of predesigned icons to choose from:

Those icons are available in black or white, ordered from 1 to 12 e.g.

  • https://scripts.sirv.com/smv/v3/b3/graphics/icons/black/icon.spin.12.svg
  • https://scripts.sirv.com/smv/v3/b3/graphics/icons/white/icon.spin.12.svg

Alternatively, you could design your own square SVG (or PNG) icon and apply it with CSS, like so:

<style>
.smv-thumbnails .smv-selector[data-type="spin"]:before {
    background-image: url(https://youraccount.sirv.com/path/to/your/spin-icon.svg);
}
</style>

If you have a mixture of 360 (left/right motion) and 3D spins (left/right & up/down motion), you can show different thumbnails for different spins. Three icon types are possible, with CSS:

<style>
/* single-row spin */
.smv-thumbnails .smv-selector[data-type="spin"].spin-x:before {
    background-image: url(https://youraccount.sirv.com/path/to/normal-spin-icon.svg);
}

/*  single-column spin */
.smv-thumbnails .smv-selector[data-type="spin"].spin-y:before {
    background-image: url(https://youraccount.sirv.com/path/to/vertical-spin-icon.svg);
}

/* multidimensional spin */
.smv-thumbnails .smv-selector[data-type="spin"].spin-xy:before {
    background-image: url(https://youraccount.sirv.com/path/to/3D-spin-icon.svg);
}
</style>

Cursor

Native browser cursors will show on hover over the image, to indicate when an image can be zoomed or dragged.

Cursors can be changed or removed with the following CSS classes:

<style>
.smv-cursor-zoom-in {
    cursor: zoom-in;
}

.smv-cursor-zoom-out {
    cursor: zoom-out;
}

.smv-cursor-dragging {
    cursor: move;
}
</style>

360 spin

Sirv Media Viewer can embed one 360 spin, many spins or a mixture of spins, images, zooms and videos.

Here’s a single 360 spin:

The code is:

<div class="Sirv" data-src="https://demo.sirv.com/spins/FishHeadSpin/Apparel/6202063/6202063.spin"></div>

Multiple 360 spins

Here’s a gallery containing many spins:

The code is simply:

<div class="Sirv">
<div data-src="https://demo.sirv.com/spins/FishHeadSpin/Apparel/6202063/6202063.spin"></div>
<div data-src="https://demo.sirv.com/spins/FishHeadSpin/Apparel/6202162/6202162.spin"></div>
<div data-src="https://demo.sirv.com/spins/FishHeadSpin/Apparel/6202961/6202961.spin"></div>
<div data-src="https://demo.sirv.com/spins/FishHeadSpin/Apparel/6203061/6203061.spin"></div>
<div data-src="https://demo.sirv.com/spins/FishHeadSpin/Apparel/6203161/6203161.spin"></div>
</div>

Auto spin & resume

You can set the spin to rotate infintely, until the user interacts with it. Set autospin to true:

It will automatically restart when the user stops interacting with it.

Streaming video

Sirv Media Viewer can embed the videos you upload to Sirv, automatically streaming them so they load fast.

Here’s a single video:

The code is:

<div class="Sirv" data-src="https://demo.sirv.com/videos/e-tron_quattro.mp4"></div>

You can embed YouTube and Vimeo videos in the same way:

The code is:

<div class="Sirv">
<div data-src="https://demo.sirv.com/videos/e-tron_quattro.mp4"></div>
<div data-src="https://www.youtube.com/watch?v=chSL_ZN3A1Y"></div>
<div data-src="https://player.vimeo.com/video/266931123"></div>
</div>

External images

Sirv Media Viewer can also display images which are not hosted in your Sirv account. External images will show as swappable thumbnails in the gallery.

The first image in this demo is on an external site:

External images are referenced with an img tag, using data-src, like this:

<div class="Sirv">
<img data-src="https://cdn.shopify.com/s/files/1/1767/1829/products/Exposure-Marine-Action-9-Plus-Torch.jpg">
<div data-src="https://demo.sirv.com/spins/spinme/exposure/exposure.spin"></div>
<iframe data-src="https://www.youtube.com/watch?v=9sBVyw_UkHc&" style="width: 100%; height: 100%;" frameborder="0" allow="encrypted-media" allowfullscreen></iframe>
</div>

Image zoom is not possible with external images, because external servers don’t have Sirv’s capability of tiling and compressing images.

If you wish to zoom external images residing on your server, enable image fetching, then change the image URLs to use your Sirv domain. Sirv will fetch them from your server, tile them, optimize them and serve them as zoomable images.

If all the images in the gallery are from an external site, a “Powered by Sirv” link will show in the corner.

API

Sirv Media Viewer is built dynamically after the page has loaded (DOM ready).

You can control the loading of the viewer with these API commands:

  • Sirv.start() – starts all instances of .Sirv on the page.
  • Sirv.stop() – stops all instances of .Sirv on the page.

In case you have multiple instances of Sirv Media Viewer on the page and need to control a particular one, specify the #id of that instance:

  • Sirv.start(<#id>) – starts the .Sirv instance with a specific #id.
  • Sirv.stop(<#id>) – stops the .Sirv instance with a specific #id.

Simultaneously, you disable “autostart” on the viewer, either via the global settings:

<script>
    var SirvOptions = {
        viewer: {
            autostart: false
        },
    };
</script>

Or via the “data-options”:

<div class="Sirv" data-options="autostart: false">

API options

Global API

window.Sirv = {
    version: 'version of sirv.js',
    build: 'build time',
    magicJS: [magicjs lib],
    image: {
        start: function (id) {},
        stop: function (id) {},
        refresh: function (id) {},
        getInstance: function (id) {}
    },
    viewer: {
        start: function (id) {},
        stop: function (id) {},
        refresh: function (id) {},
        getInstance: function (id) {},
        on: function (nameOfEvent, callback) {},
        off: function (nameOfEvent, callback) {}
    },
    start: function (id) {},
    stop: function (id) {},
    refresh: function (id) {}
};

Slider instance API

{
    isReady: function () {},
    start: function () {},
    stop: function () {},
    refresh: function () {},
    jump: function (indexOfSlide) {},
    next: function () {},
    prev: function () {},
    isFullscreen: function () {},
    fullscreen: function () {},
    child: function (numberOfSlide) {},
    on: function (nameOfSliderEvent, callback) {},
    off: function (nameOfSliderEvent, callback) {}
}

Spin instance API

{
    isInitialized: function () {},
    isReady: function () {},
    play: function (duration, effect) {},
    pause: function () {},
    rotate: function (x, y) {},
    rotateX: function (frames) {},
    rotateY: function (frames) {},
    jump: function (rows) {},
    jumpRows: function (frame) {},
    jumpCols: function (frame) {},
    zoomIn: function () {},
    zoomOut: function () {},
    isZoomed: function () {},
    currentFrame: function () {},
    getOptions: function () {}
}

Zoom instance API

{
    isReady: function () {},
    resize: function () {},
    zoomIn: function () {},
    zoomOut: function () {},
    isZoomed: function () {},
    getOptions: function () {}
}

Image instance API

{
    isReady: function () {},
    resize: function () {},
    getOptions: function () {}
}

Events

// Attach an event handler for an event
Sirv.viewer.on('[event]', function (e) {
    // ...
});
// Remove an event handler
Sirv.viewer.off('[event]', function (e) {
    // ...
});

List of slider events:

  • ready
  • beforeSlideIn
  • beforeSlideOut
  • afterSlideIn
  • afterSlideOut
  • fulscreenin
  • fulscreenout

List of spin events:

  • init
  • ready
  • zoomIn
  • zoomOut

List of zoom events:

  • ready
  • zoomIn
  • zoomOut

List of image events:

  • ready

Example of events using id:

<div class="Sirv" id="test">
    <div data-src="example.spin"></div>
    <div data-src="another.spin"></div>
    <div data-src="onemore.spin"></div>
</div>
<script src="https://scripts.sirv.com/smv/v3/b3/sirv.js"></script>
<script type="text/javascript">
    Sirv.viewer.on('ready', function (slider) {
        console.log('custom global event ready', slider);

        if (slider.id === 'test') {
            var child = slider.child();

            if (child[child.component]) {
                child[child.component].on('init', function (e) {
                    console.log('child init', e);
                });

                child[child.component].on('ready', function (e) {
                    console.log('child ready', e);
                });

                child[child.component].on('zoomIn', function (e) {
                    console.log('child zoomIn', e);
                });

                child[child.component].on('zoomOut', function (e) {
                    console.log('child zoomOut', e);
                });
            }
        }
    });

    Sirv.viewer.on('fullscreenIn', function (slider) {
        console.log('custom global event fullscreenIn', slider);
    });

    Sirv.viewer.on('fullscreenOut', function (slider) {
        console.log('custom global event fullscreenOut', slider);
    });


    Sirv.viewer.on('beforeSlideIn', function (slide) {
        console.log('custom global event beforeSlideIn', slide);
    });

    Sirv.viewer.on('beforeSlideOut', function (slide) {
        console.log('custom global event beforeSlideOut', slide);
    });

    Sirv.viewer.on('afterSlideIn', function (slide) {
        window.ttt = slide;
        console.log('custom global event afterSlideIn', slide);
    });

    Sirv.viewer.on('afterSlideOut', function (slide) {
        console.log('custom global event afterSlideOut', slide);
    });
</script>

Another example:

<div class="Sirv">
    <div data-src="example.spin"></div>
    <div data-src="another.spin"></div>
    <div data-src="onemore.spin"></div>
</div>
<div class="Sirv" id="sirv1">
    <div data-src="example.spin" id="test"></div>
    <div data-src="another.spin"></div>
    <div data-src="onemore.spin"></div>
</div>
<script src="https://scripts.sirv.com/smv/v3/b3/sirv.js"></script>
<script>
    Sirv.viewer.on('ready', function (slider) {
        if (slider.id === 'sirv1') {
            var spin = slider.child('test');
            /*
                spin === {
                    component: "spin",
                    index: 0,
                    parent: function () {},
                    isActive: function () {},
                    getSelector: function () {},
                    spin: { // spin API
                        ...
                    }
                }
            */
        }
    }
</script>

Faster initialization

To load your images faster, you can prefetch the DNS and pre-initiate the connection to Sirv resources.

Paste the code below between the <head> and </head> of your HTML page:

<link rel="preconnect" href="https://scripts.sirv.com" crossorigin/>
<link rel="preconnect" href="YOUR-SIRV-URL" crossorigin/>
<link rel="dns-prefetch" href="https://scripts.sirv.com"/>
<link rel="dns-prefetch" href="YOUR-SIRV-URL"/>

In the code, change YOUR-SIRV-URL to match your Sirv subdomain e.g. https://youraccount-cdn.sirv.com or https://youraccount.sirv.com.

This technique typically loads the Sirv Media Viewer JavaScript 100-300ms faster, for browsers that support preconnect. For browsers that only support DNS prefetch, it loads 10-150 ms faster. You can measure the time taken for DNS lookup, initial connection and SSL handshake with your browser console. In Chrome, it looks like this:

Chrome waterfall inspector - connection analysis

Was this article helpful?