Media

Sircl supports controlling media (audio and video) in your webpage, including connecting to your devices (camera's), taking pictures and scanning barcodes (if supported by your browser).

Media support

Audio and video can be included in your web pages using standard AUDIO and VIDEO tags. The Sircl media extension offers capabilities to interact with audio and video, and to implement some common usecases using only declarative (HTML) syntax and server-side processing (if needed).

The Sircl media support is an extension that requires the addition of a reference to the sircl-media.js or sircl-media.min.js file. You can install the file locally and reference it (as in the following sample), or you can reference the jsDeliver CDN version:

<script src="/lib/sircl-2.4.3/sircl-media.min.js"></script>

For more about installation options of Sircl and Sircl extensions, see the Get Started section.

Media Event-Actions

Controlling media

The Sircl media extension offers following Event-Action attributes to control media:

For instance:

<video id="video1">
  <source src="/media/samplevideo.mp4" type="video/mp4" />
</video>
<div>
  <button type="button" onclick-toggleplaymedia="#video1">Play/Pause</button>
  <button type="button" onclick-resetmedia="#video1" onclick-playmedia="#video1">Restart</button>
</div>

The last button both resets the media (to start again from the beginning), and starts playing it.

Furthermore, the classes  ifinview-playmedia and ifnotinview-pausemedia allow to control media to play only when present in the viewport (when visible). For instance:

<video class="ifinview-playmedia ifnotinview-pausemedia" autoplay muted>
  <source src="/media/samplevideo.mp4" type="video/mp4" />
</video>

Support varies from browser. Some browsers only allow playing media without a prior user interaction on the page only if the media is muted. In this example the VIDEO element has the muted attribute.

Media player events

The Media extension of Sircl also comes with a series of Event-Actions to react on media player events toat correspond to events of HTMLMediaElement. For following events, actions are defined:

• play: the media is instructed to start playing.
• waiting: the media has stopped playback because of a temporary lack of data.
• playing: the media starts or restarts effectively playing.
• pause: the media element is paused.
• ended: the media has finished playing.

Here the complete list of Action-Events to react to media player events:

The following example adds a Play and Pause button that control a media player and are visible only when relevant:

<video id="video1"
       onpausemedia-show=".show-when-paused" onplaymedia-show=".show-when-playing" 
       onplaymedia-hide=".show-when-paused" onpausemedia-hide=".show-when-playing">
  <source src="~/media/samplevideo.mp4" type="video/mp4" />
</video>
<div>
  <button type="button" class="show-when-paused" onclick-playmedia="#video1">Play</button>
  <button type="button" class="show-when-playing" onclick-pausemedia="#video1" hidden>Pause</button>
</div>

Note that the -addclass and -removeclass Event-Actions hold a value that can refer to one or more classes and one or more targets to add or remove classes on. See the section on Add/remove/toggle class values in the section Event-Actions of this documentation.

Setting media source

On an AUDIO or VIDEO element you can define the source (audio or video source to playback) through the src attribute or nested SOURCE elements.
This requires the source to be accessible through an URL.

To define mobile device camera's or webcams as  video source, Sircl offers two ways:

Setting a local video source

To define a mobile device camera or webcam as video source, you can add an onload-setvideosource attribute on the VIDEO element, where this attribute defines the value for the "facingMode" of the camera to ideally choose from. The facingMode property can have one of the following values:

• user: refers to the camera facing the user, for instance a front-facing camera on a smartphone.
• environment: refers to the camera facing away from the user, for instance the back camera on a smartphone.
• left: refers to a camera facing towards the user from its left side.
• right: refers to a camera facing towards the user from its right side.

Based on this setting, the media system of your browser will choose the best suited video source to render.

Set the autoplay attribute to start playing. Add the muted attribute if no sound is required (also increases support for the autplay attribute):

<video width="320" height="240" onload-setvideosource="environment" autoplay muted>
</video>

Choosing a local video source

Alternatively, or additionally (as both ways can be combined), let the user choose the video source from a drop-down SELECT element.

By adding the onload-addvideodevices class on a SELECT element, when the page is loaded, the SELECT control will be seeded with the list of available video sources (camera's).

By adding the onchange-setvideosource attribute with a CSS selector refering to a VIDEO element, when an element is selected from the control, it will be set as video source for the refered VIDEO control.

In addition, you can still set the onload-setvideosource attribute to choose an initial video source.

For instance:

<video id="v1" onload-setvideosource="environment" autoplay muted>
</video>
<select class="onload-addvideodevices" onchange-setvideosource="#v1">
    <option value="">(Select a source)</option>
</select>

Taking pictures

From a video source (camera or other), pictures can be taken. To do so, define an onclick-takepicture attribute on a clickable element (typically a button). The attribute's value points to the VIDEO element(s) to take picture from.

The VIDEO element a picture is taken from, must then have one or more of the following attributes defining the target for the picture:

• picture-canvas : where the attribute's value is a CSS selector to a (one or more) CANVAS element where the image should be drawn on.
  The height of the canvas will be adapted to fit the picture's aspect ratio.
  
  
• picture-fileinput : where the attribute's value is a CSS selector to an (one or more) INPUT element of type file where to put the image in.
  A picture-filename attribute can be used to define the file name (by default "picture.png").
  A picture-filetype attribute can be used to define the file's media type (by default "image/jpeg" or "image/png" based on the file name extension).
  
  
• picture-img : where the attribute's value is a CSS selector to an (one or more) IMG element in which to render the image.
  The image is then rendered as embeded data (URL of type: data:image/png;base64).
  
  
• picture-imgref : where the attribute's value is a CSS selector to an (one or more) IMG element in which to render the image.
  The image is then rendered as an URL to an object (URL of type blob:).

In the following example, a picture can be taken from the user faced camera. The picture is automatically uploaded to the server because of the onchange-submit class on the INPUT element:

<video id="v1" onload-setvideosource="environment" autoplay muted
       picture-fileinput="#uploadform INPUT[type=file]">
</video>

<button type="button" onclick-takepicture="#v1">Post your picture</button>
</div>

<form id="uploadform" action="/PostPicture" method="post" enctype="multipart/form-data">
  <input type="file" class="onchange-submit" name="picture" />
</form>

Barcode scanning

The Sircl media extension library provides you access to the Barcode Detection API which allows for linear and two-dimensional barcode recognition.

Note that this is still an experimental API and that browser support is limited.

Feature detection

The following classes can be used to show or hide page elements depending on whether the Barcode Detection API is supported by the browser:

• ifcanusebarcodescanner-show : the element decorated with this class is only visible if Barcode Detection API is supported by the browser or by a polyfill.
  
  
• ifcanusebarcodescanner-hide : the element decorated with this class is only visible if Barcode Detection API is not supported by the browser or by a polyfill.

If you want to make sure the Barcode Detection API is supported, you can add the following code in your page, before referencing the Sircl media extension library, to inject a polyfill if the browser does not support the API natively:

<!-- Barcode polyfill: -->
<!-- Source: https://github.com/undecaf/barcode-detector-polyfill -->
<script src="https://cdn.jsdelivr.net/npm/@undecaf/[email protected]/dist/index.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@undecaf/[email protected]/dist/index.js"></script>
<script>
    if (!('BarcodeDetector' in window)) { 
        window['BarcodeDetector'] = barcodeDetectorPolyfill.BarcodeDetectorPolyfill
    }
</script>

Barcode scanner

To define a barcode scanner, declare a VIDEO element with the barcode-scanner class. Also set the onload-setvideosource attribute to use the camera video source. The autoplay and muted attributes will make the scanner auto-start:

<video class="barcode-scanner" onload-setvideosource="environment" autoplay muted>
</video>

This defines a barcode scanner for QR codes only. To support different or more code formats, declare the requested formats by the barcode-formats attribute. For instance:

<video class="barcode-scanner" onload-setvideosource="environment" autoplay muted
       barcode-formats="ean_13 ean_8 upc_a upc_e">
</video>

The format codes to use are defined by the Barcode Detection API.

Unsupported formats will be ignored (you will see a warning on the Browser's Javascript console).

Through the autoplay attribute in the above examples, the barcode scanner will automatically start. As soon as a code is recognized, the barcode scanner video stream is stopped. Restart the video stream to scan a next code (i.e. by clicking an element with an onclick-playmedia attribute refering to the VIDEO element of the barcode scanner)

Navigating

To create a QR code scanner that will navigate to the URL of the scanned QR code, add the class onbarcodedetected-navigate to the barcode scanner VIDEO element:

<video class="barcode-scanner onbarcodedetected-navigate"
       onload-setvideosource="environment" autoplay muted>
</video>

The scanned code has to start with http://, https:// or mailto: in order to be followed.

Form filling-in

To have the scanned barcode submitted to the server for further processing, have the barcode filled-in in a form field. For this, the barcode scanner VIDEO element must have a onbarcodedetected-setvalue attribute where the attribute contains a CSS selector refering to the INPUT element(s) to enter the scanned barcode in.

To have the format of the scanned barcode entered in a form field, add the onbarcodedetected-setformat attribute with a CSS selector refering to the INPUT element(s) to contain the scanned barcode format:

<video class="barcode-scanner" onload-setvideosource="environment" autoplay muted
       barcode-formats="ean_13 ean_8 upc_a upc_e"
       onbarcodedetected-setvalue="#inp-code"
       onbarcodedetected-setformat="#inp-fmt">
</video>

<form id="scanform" action="/BarcodeScanned" method="post">
    <input type="text" id="inp-code" name="code" />
    <input type="text" id="inp-fmt" name="format" />
</form>

You can add an onchange-submit class to the barcode value INPUT field or its form to have the form automatically submitted as soon as a barcode is read.

Or you can use the onbarcodedetected-click attribute as explained in this next section to simulate a click on a submit button.

Clicking on scan

When a barcode is detected you can simulate a click by placing the onbarcodedetected-click attribute on the barcode scanner VIDEO element. The value of the attribute is a CSS selector to the element(s) to be clicked.

This can be used to simulate a click on a submit button, or can for instance be used in a click event chain to trigger any of the onclick-* Event-Actions.

Extensibility

Whenever a barcode is detected, a bubbling CustomEvent is triggered. The detail property of the event holds an array of detected barcodes according to the return value of the BarcodeDetector detect method's return value.

You can use this event to write your own Sircl extensions to handle barcode detection events:

<script>
    document.addEventListener("DOMContentLoaded", function () {
        $(document).on("barcodedetected", "VIDEO.barcode-scanner", function (event) {
            alert(event.detail.barCodes[0].rawValue);
        });
    });
</script>