Get powerful insights into how your audience watches your videos and listens to your audio.

Where can I get the Media Analytics?

Media Analytics is a plugin for Matomo and is available for purchase on the Matomo Marketplace as a yearly subscription. While the subscription is active you will receive all updates for this plugin.

You can also get it as a hosted solution on our Matomo Analytics (formerly Piwik Analytics) Cloud.

What does Media Analytics do?

Media Analytics measures how your videos and audio is consumed by your visitors. It lets you know how often a media was played, for how long they played it, whether they viewed it in fullscreen, how often a video was paused or resumed, gives you real time insights and much more. Media Analytics tracks your videos and audios by automatically adding a bit of JavaScript code to your Matomo Analytics (formerly Piwik Analytics) Tracker code.

Where do I get more information about this plugin?

It is recommended to visit the Media Analytics website as well as the Media Analytics plugin page on the
Matomo Marketplace as a starting point. Developer documentation can be found on the Developer Zone.

Who develops & maintains the Media Analytics plugin?

The plugin is developed and maintained by InnoCraft, the company from the makers of Matomo (Piwik). At InnoCraft, passionate product designers and engineers build and maintain the free and open source project Matomo. This ensures the highest quality and compatibility of all their plugins. As a result, popular Matomo features such as Segmentation, Row evolution, Scheduled reports and others will work out of the box.

What about the quality of this plugin?

This plugin is built and maintained by InnoCraft, the makers of Matomo (Piwik). This ensures that the plugin is well integrated, kept up to date and automatically tested whenever a change in Matomo core is made. By purchasing this plugin you also support the original developers of Matomo to maintain the free and open source analytics platform itself.

Which Matomo version is required for this plugin?

Matomo (Piwik) 2.17.0 or newer is required. You can also signup to our Matomo Cloud (formerly Piwik Cloud) service.

Which media players are currently supported?

Media Analytics currently supports HTML5 videos, HTML5 audio, YouTube, SoundCloud, Vimeo and JwPlayer (HTML5, Flash, M3U8, MPEG-DASH) videos. Players based on HTML5 like JW Player (jwplayer), Flow player (flowplayer), VideoJS, MediaElement.js, Opencast, Brightcove (HTML5), Paella Player and others are supported out of the box as well. If you use another media player such as Wistia, Ooyala, JW Platform, Vzaar and need powerful video analytics, please contact us.

Should you use Plyr media player in combination with a YouTube video the tracking won’t work. However, all other Plyr sources work fine.

What does Media Analytics look like?

You can find screenshots of the UI in the plugin preview.

There is also a video showing you some of the features:

I use a different media player that is not supported by the Media Analytics plugin, what can I do?

The Media Analytics plugin supports the addition of « custom » players. This allows you to track any media player by writing some JavaScript code linking your video player to the analytics platform. If you do not feel confident doing this or prefer to have your media player tracking built-in the Media Analytics plugin (and maintained by us), please contact us. We will be happy to consider adding awesome analytics tracking for your media player!

Which browsers are supported?

Media Analytics has been tested in several browsers and operating systems. The supported browsers depend on the used video player but most browsers are supported, including older browser versions.

How are video & audio loops handled?

When a video or audio is played in a loop, the behaviour varies depending on the used player.

  • Vimeo and HTML5 players will not trigger a new video play when the video or audio repeats. Instead, the spent time watching or listening will increase.
  • When using YouTube, every loop will be tracked as a new play and the time spent watching the video re-starts from the beginning of the video at each loop. Youtube currently lets us track the loopswhen the video is within a Youtube playlist.

Are YouTube playlists analytics provided?

Yes, you get useful analytics for your Youtube Playlists. Whenever the video changes, a new play for the new video URL and video title will be tracked.

Which metrics do I get out of Media Analytics?

Media Analytics gives you insights for many metrics for each of your video and audio, in particular:

  • How often was a page viewed, that had a video or audio included.
  • How often was a video or audio actually started.
  • How often did a visitor finish viewing a video or listening to audio.
  • How long did a visitor watch a video or listen to audio.
  • How far in the video or audio did the visitor watch or listen.
  • How often the video was viewed in fullscreen.
  • How many unique users have watched or listened to your media (where each user is counted only once).
  • How many unique users have viewed a page where a video or audio was included.

It also reports various metrics processed for each video and audio such as:

  • « Play rate »: the percentage of visitors that watched or listened to a media after they have visited a page where this media was included.
  • « Finish rate »: the percentage of visitors who played a media and finished it.
  • « Completion rate »: the percentage of how much visitors have watched of a video or listened to an audio.
  • « Fullscreen rate »: the percentage of visitors that opened a video in fullscreen.
  • « Average Time To Play »: the average amount of time it took a visitor to start playing the media since the page was loaded.
  • « Average Time spent watching »: the average amount of time a visitor spent watching or listening to a media.
  • « Average Media Length »: the average length of a video or audio media file.

Which analytics reports are provided by Media Analytics?

Media Analytics displays many reports in your Matomo Analytics (formerly Piwik Analytics). Reports are separated in several sections, depending on whether they are real-time or regular reports that are based on a selected date or date range.

Some of the Real time reports include:

  • Number of video plays (and audio plays) in the last 30 minutes and 24 hours.
  • The total time users spent playing your media in the last 30 minutes and 24 hours.
  • The most popular videos in the last 30 minutes and 24 hours.
  • A real time world map (where you can drill down to countries and regions) showing from where your current audience is playing your media.
  • The Media Audience log showing each action a particular visitor is performing on your website’s media, such as playing a video, pausing, opening in full screen, etc.

The following analytics reports can be displayed for any given date range:

  • Watched videos / audio by video title and audio title.
  • Watched videos / audio by resource URL.
  • Watched videos / audio by hour (see how your media is consumed at a different time of the day).
  • Watched videos by resolution (see how your videos are consumed when the resolution is different).
  • Watched media by media player.
  • Evolution of all metrics to see how your media performs over time.

It is possible to drill down into even more details for each particular video and audio:

  • how a specific video or audio was used at a different time of the day.
  • how a specific video or audio was played at a different resolution.
  • view the histogram of how far and how long each media was watched.

On top, popular Matomo features are supported:

How do I view the detailed video analytics for a particular video?

To drill down and view detailed report for a specific video, go to Media > Video reports, then look for the video you are interested in. You may use the search feature at the bottom of the table to find your video. Then hover on the data table row for this video and click the lens/zoom icon. The detailed video analytics (or audio analytics) for this specific media will open and will display:

  • how this video / audio was used at a different time of the day.
  • how this video / audio was played at a different resolution.
  • the detailed histogram of how far and how long this media was watched by your users.

Is it possible to see an evolution of my media consumption?

Yes, you can drill down into the evolution for each individual video and audio to see how the consumption of a particular media changes over time. Matomo (Piwik) lets you select the metric you are interested in and see the evolution over the last days, weeks, months or years.

Is it possible to segment data by media usage?

Yes, Media Analytics lets you segment your audience in advanced ways. Matomo (Piwik) will let you:

  • Segment your visitors by how long they played a media.
  • Segment your visitors by the length of the media they played.
  • Segment your visitors by played media title.
  • Segment your visitors by played media resource URL.
  • Segment your visitors and show only visitors that watched a video or listened to audio.
  • Segment your visitors by how long they waited on a page before they played a media.

This lets you slice and dice your analytics reports exactly how you need to extract valuable insights into your audience.

Can I export Media Analytics reports and embed them somewhere else?

Yes, you can export all Media Analytics reports, including the Real Time reports and embed them via an iframe into a different website or app. You can also get the reports sent by email to you or your colleagues and customers. If you need access to the raw data, you can use the Live API or directly access the raw data in your MySQL database.

Will the reports be shown in the Matomo Mobile app for Android and iOS?

Yes, most media reports will be shown in the Matomo (Piwik) mobile app. Only the real time media reports are not yet supported by the mobile app.

Does playing a media keep the visit session of a visitor alive?

Yes, it does. By default Matomo (Piwik) starts a new session / visit when a user is inactive for 30 minutes. When viewing a video or listening to audio, the session will be kept alive and extended every few seconds. This prevents creating many new visits when a visitor watches a video for a long time (longer than 30 minutes).

How often is the current progress of a media updated when a visitor is playing it?

By default, the user watching a video or listening to an audio will be tracked every 5 seconds and whenever the player is interacted with by the user (such as when clicking pause, resume or fullscreen). To change the tracking interval, you can call the following tracking method:

 // sends an update every 2 seconds to get more accurate results (this causes more server load)
 var intervalInSeconds = 2;
 _paq.push(['MediaAnalytics::setPingInterval', intervalInSeconds]);

Why are some media titles « Unknown »?

The media tracker only receives a media title from the YouTube and Vimeo player but not from other players such as HTML5.
Media Analytics plugin attemps to detect a media title from the tooltip and alternate text HTML attribute. If these are not set, the media title cannot be tracked and they will be reported as « Unknown ». The developer guide for enriching media data explains how to avoid unknown media titles and how to track a proper media title for all of your videos and audios.

How do I track my videos when I am using the jQuery fancyBox plugin?

When you initialize the fancy box plugin, we recommend to add a custom property « afterLoad » like this:

  afterLoad: function () { 
  width: 576, 
  height: 320, 
  type: ‘iframe’, 
  helpers : { media : {} } 

Does Media Analytics work with the SoundManager 2 library?

Yes, Media Analytics detects the SoundManager 2 library automatically and tracks your audio if HTML5 is enabled.

Can I exclude URL parameters that are shown in the media resource report?

Yes, all parameters that are defined in your config/config.ini.php file (in the [General] url_query_parameter_to_exclude_from_url configuration) are excluded from your media URLs. For example sid and sessionid will be automatically removed. If you cannot find this configuration in your config file, the default URL parameter values will be excluded, as defined in config/global.ini.php.

Additionally, URL parameters from the [MediaAnalytics] media_analytics_exclude_query_parameters configuration are excluded from your tracked URLs. The URL parameters enablejsapi and player_id are excluded by default. You may customize the list by specifying, in your config/config.ini.php:

media_analytics_exclude_query_parameters = "enablejsapi,player_id,loop,autoplay"

How is the grouped media resource report different to the media resource report?

The « grouped media resource » report displays a flat report which includes both the domain and the path to the media resource, whereas the regular « media resource » report displays a hierarchical view of your media resources by domain. In the grouped resource report, any file extensions (such as mp4 and mov) and any URL query parameters are removed. This is useful if you offer your videos or audio in different formats, as the report will give you a clean aggregated view of a single media resource.

How do I change the interval of how often the real time reports are updated?

Specify the following configuration entry in your config/config.ini.php:

live_widget_refresh_after_seconds = 10
; defaults to 5 seconds

Please note that changing this config value also changes how frequent the « Visitors in Real Time » widget is updated.

What is a media « impression » and « impression rate »?

An impression is the number of times one of your visitors had viewed a page where a video or audio was included.

It does not mean the media was actually played by the visitor. As soon as the visitor starts the video or audio, a « play » event is tracked. The ratio of how many users play your content VS how many users have loaded a page with the content included in the page, is represented as the « play rate ». For example if 100 visitors have been on a page that included a particular video, and 30 of it have actually started it, the play rate is « 30% ».

What does the metric « Time to initial play » mean?

When a visitor views one of your pages which contains a media, the time time when the page was loaded is measured.
When a visitor then plays a media on your page, Media Analytics processes how many seconds have elapsed since the page was loaded by this user. The difference is the « Time to initial play ». For example if a visitor opens a webpage at « 12:25:35 » and starts playing the video at « 12:25:41 », the time to initial play is 6 seconds.

How do I see a map showing from where my audience is?

The real time map showing your current audience, and a regular map showing where your users came from at a particular date and date range, are both available in the Media menu in your analytics dashboard. The map displays your users by continent, country and you can go down to particular regions and cities. To use this feature make sure Geolocation is set up correctly in your Matomo Analytics (formerly Piwik Analytics).

How do I see how visitors are consuming and using my media?

In the « Audience Log » you can see each individual visitor that has played one of your media. It shows how your visitor have played, paused, resumed and finished all of your media. You can also see how each visitor navigated through your website before actually playing a media and which page they moved on to after playing a media.

How do I get aggregated reports for weeks, months, year and custom date ranges?

Matomo allows you to view all reports by day, week, month, year and custom date ranges (via the calendar selector)

Additionally there are several reports that show the usage of your media in real time, for example usage in the last 30 minutes, last 24 hours. Go to Matomo > Media > Real-time to view these reports.

Why do some visitors have triggered many pause and resume events?

There can be many reasons for this. For example we have noticed this behaviour quite often when the media was not loading as fast and the media was buffering quite often. Visitors then tend to pause for a second to wait for the media to load a bit more before they play it again.

How do I get started tracking Media Analytics data?

In many cases the plugin only needs to be installed and from there automatically collects data. In some cases you need to do additional steps. Learn more about setting up Media Analytics tracking.

Can I disable the tracking of individual videos and audio?

Yes, you can exclude media from being tracked by specifying a data-piwik-ignore attribute. Read more about this in the guide for restricting tracked media data.

How do I disable the tracking of all media for a specific site?

You can prevent the tracking of any media data by calling _paq.push(['disableMediaAnalytics']); in your website’s analytics tracking code. This is especially useful when you want to measure the usage of your media only for some of your websites, but not for all of them. Read more about this in the guide for restricting tracked media data.

How do I enable or disable the tracking of all media events?

Please note that below guide is only about disabling or enabling media events. All other media data for the media analytics reports are always tracked by default.

These media events also appear in the visits log:

Matomo Cloud

On the Matomo Cloud media player interactions like play, seek, pause and resume are not tracked as events by default as each event counts towards your hit’s quota.

You can enable the tracking of media events like play or pause by adding the below JavaScript tracking code to your website:

window._paq = window._paq || [];

You can also email the Matomo Cloud support to enable the tracking of these events by default and then you won’t need to make any changes to your tracking code.

If you have been on the Cloud since 2021 or before, then media events may be tracked by default. In this case you can disable the tracking of media events by adding the below JavaScript tracking code to your website:

window._paq = window._paq || [];

Matomo On-Premise and Matomo for WordPress

Media player interactions are automatically being tracked as events like play, seek, pause and resume.

To disable the tracking of these events for a particular site, add the below JavaScript code to your website:

window._paq = window._paq || [];

To disable the tracking of events by default for all of your sites, set below setting in your Matomo config/config.ini.php.

enable_event_tracking_by_default = 0

More information

Click here for more detailed developer documentation about Media Analytics.

How do I customize the tracking of my media?

There are many ways to customize which data is tracked and how. All the features are documented in the Media Analytics developer documentation.

Does Media Analytics work with a single webpage application?

Yes, for your single page application, you can execute a method to rescan the entire DOM or parts of the DOM for new media. Read more about scanning the DOM for new media.

Can I track live event streaming videos?

Yes, Media Analytics will also track your live event streaming videos!

Does the video tracker and audio tracker add a lot of data to the Matomo JavaScript tracker?

No, the Media tracker only adds a few kilobytes to your Matomo (Piwik) JavaScript tracker piwik.js. Having a small footprint and minimizing the tracker size is very important to us.

Can I fetch Media Analytics reports via the Matomo HTTP Reporting API?

Yes, all reports including the real time reports can be fetched in different formats such as JSON, XML, CSV, HTML and more, so you can integrate your media analytics data anywhere. Read more about the Matomo (Piwik) HTTP Reporting API and view the Reporting API Reference.

Do I get access to the raw data that was tracked?

Yes, the raw data is accessible by using the Matomo (Piwik) Live Reporting API. Additionally if you host Matomo yourself, you get access to all data that is stored in your MySQL database: the data is stored in the matomo_log_media table.

Learn more about exporting the raw data

Can I be alerted by email or text message, when any of my video or audio gets significantly more (or less) views?

Thanks to our integration with the Matomo Analytics (formerly Piwik Analytics) Alerts service, you can create custom alerts and be notified whenever any of your videos, or audios, will get significantly more (or less) traffic. Or you can get notified when the Total spent watching media changes, or when the overall number of video plays or video finishes changes. Your imagination and requirements are the limit!

Under what license is the Media Analytics tracker released?

Media Analytics and Media Analytics tracker are released under the InnoCraft EULA.

How do I exclude employees or partners views and clicks from the video and audio analytics reports?

See our FAQ: Excluding traffic from Matomo (Piwik) using IP Addresses, Cookies, and more.

How do I fix an « Allowed memory size exhausted » error in Media Analytics?

In some very rare cases you might see a memory error caused by Media Analytics if you are tracking hundreds of thousands of different media URLs per day. This can typically be the case if every media resource URL includes a random URL parameter such as key in the below example:

In this case you could avoid this memory issue by excluding the URL parameter that changes every time. In above example the URL parameter to exclude would be key. To exclude this parameter locate your local config file in $matomoDir/config/config.ini.php and tweak the media_analytics_exclude_query_parameters setting which by default only excludes the two URL parameters enablejsapi and player_id:


Simply append any randomly changing URL parameter to the media_analytics_exclude_query_parameters setting separated by a comma. This will not only fix the memory issue but also improve your reports since the number of views and plays will no longer be always 1 but can be accurately calculated based on the number of visits that viewed and played a particular media.

If you want to fix the issue retrospectively, you can execute the following SQL query in your database. Make sure to adjust the matomo_ database table prefix if needed, the idSite, and the URL parameter key

update matomo_log_media set resource = substring_index(resource, '?key', 1) where idsite = 1 and server_time > date_sub(NOW(), INTERVAL 1 week) and resource like '%?key%'

If above does not fix your issue

If you are still getting a memory error from Media Analytics you may want to limit the number of rows per subtable by changing the default value of 1000 to 500 or an even lower value in your config/config.ini.php:


Is there any data limit to how many videos can be tracked or how many events?

No, there is no data limit with the Media Analytics product. You can track an unlimited number of videos, audios, and the number of media events (play, pause, fullscreen, finishes, etc.) tracked for your users is also unlimited. Learn more about No data limit.

How do I get the the total number of Impressions and Plays for Media from the Matomo database?

We can get the total number of « Impressions » and « Plays » for both audio and video by querying the log_media table in the Matomo database.


To get the total number of « Impressions » for video media, we can use the following SQL query:

SELECT * FROM matomo_log_media WHERE idsite LIKE 'X' AND media_type LIKE '1';

As we can see from the query above, video media is stored as media_type « 1 » in the Matomo database. For video media, a « Play » is stored in the database in the watched_time column as a value above 1, any value above 1 means that the video was played at least in part.

To get the total number of « Plays » for video media we can use the following SQL query:

SELECT * FROM matomo_log_media WHERE idsite LIKE 'X' AND media_type LIKE '1' AND watched_time > '1';


Media type « Audio » is stored as media_type « 2 » in the log_media table, so for example we can retrieve all of the « Audio Impressions » with the following query:

SELECT * FROM matomo_log_media WHERE idsite LIKE 'X' AND media_type LIKE '2';

For Audio media stored in the log_media table, a « Play » is counted when the watched_time column value is greater than 1. (Any row with media_type 2 and watched_time of 1 or 0 indicates that it was not played)

So for example, we can retrieve all of the « Audio Plays » with the following query:

SELECT * FROM matomo_log_media WHERE idsite LIKE 'X' AND media_type LIKE '2' AND watched_time > '1';

If you would like to query other types of RAW tracking data from the Matomo database, you can see our FAQ here: How do I write SQL queries to select visitors, list of pageviews, searches, events in the Matomo database