---
title: "Web Player and Application Guidelines"
slug: "web-player-and-application-guidelines"
updated: 2024-02-27T19:57:23Z
published: 2024-02-27T19:57:23Z
canonical: "help.tritondigital.com/web-player-and-application-guidelines"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.tritondigital.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Player and Application Guidelines

In order to calculate accurate metrics, the audio player and application must make the proper calls to the streaming or pure play services. To limit the quantity of audio that is pushed by a streaming server and not listened to, or to limit the quantity of audio that is listened to and never counted in the audience metrics, the player and application creators must follow these guidelines.

Note that during the implementation process, Triton Digital conducts publisher audits on all new WCM clients in order to ensure content delivery networks (CDNs) are not manipulating data and we are reporting valid metrics. Triton Digital also tests and verifies that the guidelines described below are respected.

## Stop vs. Pause

Unless the streaming server can actually hold the stream and pause the content, the application and player must stop the stream and resume with a new press of the **Play** button. This results in two distinct sessions, and no audio will be pushed while the listener is on "Stop." (Also see: [HTML5 <audio> Element Considerations: Stopping the Audio](/v1/docs/web-player-and-application-guidelines#html5-consideration-stopping-the-audio).)

## Auto-play

Flag that indicates if the session has been initiated from a player auto-play. Possible values are **autoplay=0** (not initiated via auto-play) and **autoplay=1** (initiated via auto-play). Auto-play of audio content is strongly discouraged since in some cases, auto-played streams are not audible as the volume may be muted while the stream continues to be active. Triton Digital recommends that any initiation of audio content playback is determined by an overt user gesture, such as a tap or a click.

## Start and Stop at the Right Moment

The audio stream must start only when the listener presses the **Play** button.

When a listener presses the **Stop** button, closes a player browser's tab, or closes an application, the audio must stop for the listener and the request to stop must reach the streaming server.

The streaming server must properly report the timing. All streaming servers must use the official Coordinated Universal Time (UTC).

If the player/app is using the **Triton Digital Listener Tracking (LT) service**, it should send an LT ping on the **Stop**. This allows the last chunk of audio to be measured.

Web players and applications must properly support the mobile device default “control player.” This is the actual player that can **stop/pause** or **play/resume** audio-video content from the locked screen.

Also see: [HTML5 <audio> Element Considerations: Pre-load/Pre-fetch](/v1/docs/web-player-and-application-guidelines#html5-consideration-preloadprefetch).

## Muted/Audibility Requirement

The player or application must consider that *audibility* is a requirement for the digital audio content to be measured. Therefore, when applicable, the player or application must be able to detect the device "mute" and "unmute" states and/or "zero volume/nonzero volume" events in a similar manner as **Stop/Play** events. "Zero volume" must be treated the same as "mute."

## Direct Links on Web Browsers

Web Players must never open streaming MP3 or AAC URLs directly in the web browser internal players. Although the browser may use its internal player to play the audio content, it is known that these internal players may produce invalid traffic.

## Long Sessions

From a player/app perspective, it's a good practice to make sure there is user interaction after multiple hours.

## Use of Visitor (Listener) ID for LT Methodology

As listed in the LT API documentation, a unique identifier is required for each listener in order to properly calculate the CUME. This visitor identifier should represent a unique key that refers to a listener subscription for the publisher. Triton Digital uses that property with no modification and the publisher can obfuscate the property if they wish.

## Cache-busting Required for LT Methodology

A cache-busting random number or time stamp must be used with the LT Methodology. This number must be different on each new call to avoid any cached returns from a browser or proxy. A 32-bit random number or time stamp is perfectly suited for this.

## HTML5 Consideration: Pre-load/Pre-fetch

**Pre-fetching of audio content is strongly discouraged**. In most situations, the audio stream will not be heard by the listener and therefore should not be counted as a valid session. The best way to avoid measurement issues with pre-fetching is to simply **not use it**. The recommendations outlined below should work to eliminate the problem.

- **Preferred**: the **<audio>** element’s **preload** attribute should be set to **none**.  It should never be set to **auto** or left **blank**, as those options transfer the decision to the browser itself. *See the Code Example, below*.
- **Alternatively**, the **<audio>** element’s **preload** attribute includes the **metadata** option, which fetches/pre-loads only the audio metadata. *This might not cause a problem*. However, if you choose to use **preload="metadata"** instead of **preload="none"** you should thoroughly test the player on multiple platforms and browsers to be sure it’s really needed and behaves as expected.

## HTML5 Consideration: Stopping the Audio

**Important!** The HTML5 **<audio>** element does not have a true "**stop**" function, only a "**pause**." Some live streams – particularly Icecast – are seen by the browser as "a big file to download" instead of a live stream. In such cases, downloading may continue in the background when the stream is paused. To work around this, some additional actions to halt the stream/file download should be done by the web page where the player is embedded, and those actions can differ per browser and operating system. In most cases, the **<audio>** element should be told to perform another action such as "load something else to play" when the user action to **pause** is initiated. *The "something else" does not even need to actually play*.

The [HTML5 specification](https://html.spec.whatwg.org/multipage/media.html#location-of-the-media-resource) states:

> If a **src** attribute of a media element is set or changed, the user agent must invoke the media element's media element load algorithm. (Removing the **src** attribute does not do this, even if there are **source** elements present.)

Due to Apple's implementation of the HTML5 specification in the Safari browser on **iOS** and **macOS**, when a player in a **Safari web browser tab** is paused, the audio stops playing but the data continues to stream in the background until the browser tab is closed. The same happens if an iOS device is streaming via a web player in Safari for iOS and the user presses the device's power button to shut off the device's screen. In the Chrome browser on iOS, the user needs to stop all streams in the browser.

See [Code Example 1](/v1/docs/web-player-and-application-guidelines#code-examples) below for an example of how the [**Triton Digital Web Player 2.9 SDK**](/v1/docs/triton-web-player-sdk) implements a workaround to the above issues. Note that iOS stops the stream only after one minute unless the browser tab is closed (in which case the stream stops immediately). The workaround on iOS Safari involves:

- Call **pause()** on the audio node
- Do not clear the **src** attribute of the audio node.

**Other actions can be:**

- A simple reload of the page containing the player. (*This is the easiest solution, and the one that tests well in all situations we have evaluated so far, but it might not be appropriate for everyone. It depends on the complexity of the page being reloaded*.)
- Play a **known valid audio file**, such as one that plays a few seconds of silence.
- Load a **blank (""**), or "**About:blank**" value into the source attribute.
- Change the source to a **dummy mount**: `http://&lt;YOUR-AUDIO-STREAM&gt;/invalidmount`

See Code Example 2 and Code Example 3, below, for more information.

### *Code Examples*

##### Code Example1: Stopping the Audio

The example code below stops the audio and uses a workaround for the Safari browser "pause" issue.

```javascript
stop: function () {        
         var context = this;
         if ( fsm.is( STATE.STOPPED ) ) return;
         
         this.audioNode = getAudioNode.call( this );
 
         fsm.stop();
         
         this.audioNode.pause();
         if( OsPlatform.name !== 'Safari'  || this.audioNode.src.indexOf('m3u8') > -1 || this.useHlsLibrary) {
                 setTimeout(function(){
                         context.audioNode.src = '';
                         context.url = null;
                         context.resetAudioNode();
                  }, 300);
         }else{
                 setTimeout(function(){
                         context.url = null;
                         context.resetAudioNode();
                  }, 300);
         }
 
         if( OsPlatform.os.family === 'iOS' && OsPlatform.name === 'Chrome Mobile') {
                 window.stop();                        
         }
                         
          if ( this.useHlsLibrary ) {
                 this.hls.detachMedia();
                 this.hls.stopLoad();
                 this.hls.destroy();
          }      
 },
```

##### Example 2: Reloading the page

The example code below shows the use of **preload="none"** and the reloading of the page containing the player.

**<audio controls preload="none" height="32" width="300" onpause="location.reload();" src="<PLAYER PAGE URL>" type="audio/mpeg" />**

**Code notes:**

- Replace "**<PLAYER PAGE URL>**" with the actual URL to your player page.
- The **height** and **width** attributes shown are just examples; use the actual height and width of your player.

##### Example 3: Using a known valid audio file

The example code below shows the use of **preload="none"** and the loading of a short MP3 file (*a known valid audio file*) to stop the background file download.

```javascript
<audio controls preload="none" height="32" width="300" onplay="startAudio();" onpause="stopAudio();"
      src="http://download.andomedia.com/Creative/208/0/2080711_1.mp3" type="audio/mpeg" />
<script>
//     -- Set audio source before playing in case the pause/stop button has cleared it                                        
function startAudio()
      {
      var audio = document.getElementsByTagName("audio")[0];
      if (audio.src!="http://<YOUR-AUDIO-STREAM>")
             {
                    audio.src="<YOUR-AUDIO-STREAM>";
                    if(navigator.userAgent.toLowerCase().indexOf('firefox') > -1){ audio.load(); }
                    audio.play();
             }
      }
//     -- Clear the audio source - this should stop the download.  Pausing alone will not.
function stopAudio()
      {
      var audio = document.getElementsByTagName("audio")[0];
      audio.src="http://download.andomedia.com/Creative/208/0/2080711_1.mp3";
      if(navigator.userAgent.toLowerCase().indexOf('firefox') > -1){ audio.load(); }
      }
</script>
```

**Code notes:**

- Replace `http://&lt;YOUR-AUDIO-STREAM&gt;` with the actual URL to your audio stream.
- **audio.src="http://download.andomedia.com/Creative/208/0/2080711_1.mp3"** is a live three-second silent audio file hosted by Triton Digital that you can use while testing. If you choose to use this method after testing, please replace this URL with a link to your own silent audio file. *The Triton Digital file could be renamed or removed at any time without notice*.