{"id":21065639,"url":"https://github.com/adaptlearning/adapt-contrib-media","last_synced_at":"2025-05-16T02:33:30.296Z","repository":{"id":12316171,"uuid":"14951131","full_name":"adaptlearning/adapt-contrib-media","owner":"adaptlearning","description":"A basic media component that displays video and audio. This component uses the HTML5 video and audio specification and has a flash fallback for browsers that don't support HTML5.","archived":false,"fork":false,"pushed_at":"2025-05-07T12:47:32.000Z","size":10790,"stargazers_count":7,"open_issues_count":17,"forks_count":54,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-05-07T13:47:36.383Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adaptlearning.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-12-05T10:57:18.000Z","updated_at":"2025-04-02T19:46:34.000Z","dependencies_parsed_at":"2023-01-11T20:18:55.397Z","dependency_job_id":"deedd3f7-6300-4fe4-ae79-e95daabd409e","html_url":"https://github.com/adaptlearning/adapt-contrib-media","commit_stats":null,"previous_names":[],"tags_count":68,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-media","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-media/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-media/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-media/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adaptlearning","download_url":"https://codeload.github.com/adaptlearning/adapt-contrib-media/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254456382,"owners_count":22074166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T17:55:52.198Z","updated_at":"2025-05-16T02:33:29.977Z","avatar_url":"https://github.com/adaptlearning.png","language":"JavaScript","readme":"# adapt-contrib-media\n \n\u003cimg src=\"https://github.com/adaptlearning/documentation/blob/master/04_wiki_assets/plug-ins/images/media02.gif\" alt=\"image of media component\" align=\"right\"\u003e\n\n**Media** is a *presentation component* bundled with the [Adapt framework](https://github.com/adaptlearning/adapt_framework).\n\nThis component is media playback component for both audio and video. It uses HTML5 audio and video for browsers that support it and a Flash fallback for browsers for when HTML5 audio/video isn't supported or can't be used (see the [Notes](#notes) section for more information).\n\nThe component uses [MediaElement.js (v2.21.2)](http://mediaelementjs.com/), a player with a number of useful features including subtitles and accessible (and CSS-skinnable) controls. [MediaElement.js](https://github.com/johndyer/mediaelement) carries the MIT license compatible with Adapt.\n\nWhilst the underlying MediaElement player does have support for playing both YouTube and Vimeo videos, this no longer works very well due to changes in the YouTube/Vimeo player APIs - it is therefore strongly suggested you use the dedicated [YouTube](https://github.com/adaptlearning/adapt-youtube) / [Vimeo](https://github.com/adaptlearning/adapt-contrib-vimeo) components instead.\n\n[Visit the **Media** wiki](https://github.com/adaptlearning/adapt-contrib-media/wiki) for more information about its functionality and for explanations of key properties.\n\n## Installation\n\nAs one of Adapt's *[core components](https://github.com/adaptlearning/adapt_framework/wiki/Core-Plug-ins-in-the-Adapt-Learning-Framework#components),* **Media** is included with the [installation of the Adapt framework](https://github.com/adaptlearning/adapt_framework/wiki/Manual-installation-of-the-Adapt-framework#installation) and the [installation of the Adapt authoring tool](https://github.com/adaptlearning/adapt_authoring/wiki/Installing-Adapt-Origin).\n\n* If **Media** has been uninstalled from the Adapt framework, it may be reinstalled. With the [Adapt CLI](https://github.com/adaptlearning/adapt-cli) installed, run the following from the command line:\n\t```console\n\tadapt install adapt-contrib-media\n\t```\n  Alternatively, this component can also be installed by adding the following line of code to the *adapt.json* file:\n\t```json\n\t\"adapt-contrib-media\": \"*\"\n\t```\n  Then running the command:\n\t```console\n\tadapt install\n\t```\n  (This second method will reinstall all plug-ins listed in *adapt.json*.)\n\n* If **Media** has been uninstalled from the Adapt authoring tool, it may be reinstalled using the [Plug-in Manager](https://github.com/adaptlearning/adapt_authoring/wiki/Plugin-Manager).\n\u003cdiv float align=right\u003e\u003ca href=\"#top\"\u003eBack to Top\u003c/a\u003e\u003c/div\u003e\n\n## Settings Overview\n\nThe attributes listed below are used in *components.json* to configure **Media**, and are properly formatted as JSON in [*example.json*](https://github.com/adaptlearning/adapt-contrib-media/blob/master/example.json). Visit the [**Media** wiki](https://github.com/adaptlearning/adapt-contrib-media/wiki) for more information about how they appear in the [authoring tool](https://github.com/adaptlearning/adapt_authoring/wiki).\n\n## Attributes\n\n[**core model attributes**](https://github.com/adaptlearning/adapt_framework/wiki/Core-model-attributes): These are inherited by every Adapt component. [Read more](https://github.com/adaptlearning/adapt_framework/wiki/Core-model-attributes).\n\n### \\_component (string):\nThis must be set to `\"media\"`.\n\n### \\_classes (string):\nCSS class name(s) to be applied to this component’s containing `div`. The class(es) must be predefined in one of the Less files. Separate multiple classes with a space.\n\n### \\_layout (string):\nDefines the horizontal position of the component in the block. Acceptable values are `\"full\"`, `\"left\"` or `\"right\"`.\n\n### instruction (string):\nThis optional text appears above the component. It is frequently used to guide the learner’s interaction with the component.\n\n### \\_setCompletionOn (string):\nDetermines when Adapt will register this component as having been completed by the learner. Acceptable values are `\"inview\"` (triggered when the component is fully displayed within the viewport), `\"play\"` (triggered when playback is initiated), or `\"ended\"` (triggered when the video has reached the end of playback).\n\n### \\_useClosedCaptions (boolean):\nIf set to `true`, the component will allow for closed captions support when playing video. The default is `false`.\n\n### \\_startLanguage (string):\nIf using closed captions, use this property to specify which language should be shown by default - or to prevent closed captions from being shown by default (so that the learner will need to switch them on). The value of this property must match one of the `srclang` values - or be set to `\"none\"` if you need the default to be 'closed captions off'.\n\n### \\_allowFullScreen (boolean):\nDetermines whether fullscreen mode is available or not. The default is `false`.\n\n### \\_aspectRatio (string):\nDefines the aspect ratio of the video to either be landscape (16:9), portrait (9:16), or square (1:1). Acceptable values are `\"landscape\"`, `\"portrait\"` or `\"square\"`. The default is `\"landscape\"`.\n\n### \\_playsinline (boolean):\nIf set to `true`, videos will play 'inline' on iPhones (the same way they do on iPads). Note that this feature is only available in iOS10 and above. The default is `false`.\n\n### \\_pauseWhenOffScreen (boolean):\nIf set to `true`, playback will automatically be paused when the media component is 'off screen'. The default is `false`.\n\n### \\_preventForwardScrubbing (boolean):\nIf set to `true`, the component will *attempt* to prevent learners from 'skipping ahead' in media (both audio and video).  Learners can skip backwards, and back up to the `maxViewed` time tracked by `updateTime`. Note: This does not apply to full screen iOS/iPadOs - and learners using certain browsers (Internet Explorer, for example) may be able to circumvent this rule by using video play speed options. Once the learner has completed the media component, this restriction will no longer be enforced. You should therefore ensure the `_setCompletionOn` setting is set to `\"ended\"` when using this setting.\n\n### \\_offsetMediaControls (boolean):\nIf set to `true`, the media control bar will be respositioned below the media container to remove the standard overlap style. The default is `false`.\n\n### \\_showVolumeControl (boolean):\nControls whether the volume controls will be shown in the media player control bar or not. Note that this setting has no impact when the device itself - iPhone, for example - enforces its own player controls. The default value is `false`.\n\n### \\_startVolume (string):\nDefines the default volume as a percentage. This can be set with or without the percentage sign in the string. The default value is `\"80%\"`. Note that this setting has no impact on mobile devices.\n\n### \\_media (object):\nThe media object will contain different values depending on the type of media: video or audio.\n\nFor video it contains values for `mp4`, `webm`, `ogv`, `poster`, and `cc`. The properties `mp4`, `webm` and `ogv` are all optional, but at least one is required (see below for alternate properties for YouTube/Vimeo video).\n\nFor audio it contains `mp3` and `ogg`. As with video, both are optional, but at least one is required.\n\nThe decision to include more than one file format is typically based on the browser/s used by the target audience. The most widely supported video file format is [mp4](http://caniuse.com/#feat=mpeg4) (specifically [H.264/MPEG-4 Part 10 AVC](https://en.wikipedia.org/wiki/H.264/MPEG-4_AVC)). The most widely supported audio format is mp3.\n\n#### mp4 (string):\nFile name (including path) of the video file. Path should be relative to the `src` folder (e.g., `\"course/en/video/video-1.mp4\"`).\n\n#### webm (string):\nFile name (including path) of the video file. Path should be relative to the `src` folder (e.g., `\"course/en/video/video-1.webm\"`).\n\n#### ogv (string):\nFile name (including path) of the video file. Path should be relative to the `src` folder (e.g., `\"course/en/video/video-1.ogv\"`).\n\n#### poster (string):\nFile name (including path) of the optional image to be shown while the video is downloading, or until the learner hits the play button. If this is not included, the first frame of the video will be used instead. Path should be relative to the `src` folder (e.g., `\"course/en/video/video-1-poster.jpg\"`).\n\n#### cc (array):\nClosed captions in multiple languages may be provided. Each entry in this array should be an object, containing the following settings:\n\n##### srclang (string):\nThe language of the closed captions (e.g., `\"en\"` for English). Acceptable values can be found at http://www.w3schools.com/tags/ref_language_codes.asp.\n\n##### src (string):\nFile name (including path) of the closed captions resource accepted by `\u003ctrack\u003e` (e.g. a [the VTT file](https://developer.mozilla.org/en-US/docs/Web/API/Web_Video_Text_Tracks_Format)). Path should be relative to the `src` folder (e.g., `\"course/en/video/video-1-subtitles.vtt\"`).\n\n#### mp3 (string):\nFile name (including path) of the audio file. Path should be relative to the `src` folder (e.g., `\"course/en/audio/audio-1.mp3\"`).\n\n#### ogg (string):\nFile name (including path) of the audio file. Path should be relative to the `src` folder (e.g., `\"course/en/audio/audio-1.ogg\"`).\n\n### \\_transcript (object):\nThe transcript object contains the following settings:\n\n#### \\_setCompletionOnView (boolean):\nDetermines whether Adapt will register this component as having been completed by the learner when the inline transcript is opened. The default value is `true`.\n\n#### \\_inlineTranscript (boolean):\nDetermines whether the button that toggles the display of the inline transcript text will be displayed or not. The default value is `false`.\n\n#### \\_externalTranscript (boolean):\nDetermines whether the button that links to the optional external transcript will be displayed or not. The default value is `false`.\n\n#### inlineTranscriptButton (string):\nThis text appears on the button that toggles the visibility of the inline transcript text. It is displayed when the inline transcript text is hidden. If no text is provided, the `\"transcriptLink\"` will be displayed on the button.\n\n#### inlineTranscriptCloseButton (string):\nThis text appears on the button that toggles the visibility of the inline transcript. It is displayed when the inline transcript text is visible.\n\n#### inlineTranscriptBody (string):\nThis optional text appears below the video. If provided, its visibility is toggled by clicking the transcript button. It is hidden by default.\n\n#### transcriptLinkButton (string):\nThis text appears on the button that links to the optional external transcript. If no text is provided, the `\"transcriptLink\"` text will be displayed on the button.\n\n#### transcriptLink (string):\nFile name (including path) of the optional external transcript. Path should be relative to the `src` folder (e.g., `\"course/en/pdf/video01_transcript.pdf\"`).\n\n### \\_playerOptions (object):\nThis optional object can be used to customize the player. See [*example.json*](https://github.com/adaptlearning/adapt-contrib-media/blob/master/example.json) for a list of settings. Please note: as these settings are not implemented by the Adapt community, there is no guarantee that all features and combinations thereof will be compatible with your device set up.\n\n\u003cdiv float align=right\u003e\u003ca href=\"#top\"\u003eBack to Top\u003c/a\u003e\u003c/div\u003e\n\n### JSON Examples\n\nThe attributes described above focus on the component's use with standard video. They are properly formatted as JSON in [*example.json*](https://github.com/adaptlearning/adapt-contrib-media/blob/master/example.json) The same model can be applied to the component's use with audio and YouTube videos.\n\n#### Standard video example:\n```json\n\"_media\": {\n\t\"mp4\": \"course/en/video/video.mp4\"\n},\n```\n\n#### YouTube video example:\n```json\n\"_media\": {\n\t\"source\": \"//www.youtube.com/watch?v=RT-KmgAgxuo\",\n\t\"type\": \"video/youtube\"\n},\n```\nNote: it is strongly suggested you use the dedicated [YouTube component](https://github.com/adaptlearning/adapt-youtube) if you want to include YouTube videos in your Adapt course.\n\n#### Vimeo video example:\n```json\n\"_media\": {\n\t\"source\": \"//player.vimeo.com/video/96961553\",\n\t\"type\": \"video/vimeo\"\n},\n```\nNote: it is strongly suggested you use the dedicated [Vimeo component](https://github.com/adaptlearning/adapt-contrib-vimeo) if you want to include Vimeo videos in your Adapt course.\n\n#### Audio example:\n```json\n\"_media\": {\n\t\"mp3\": \"course/en/audio/audio.mp3\",\n\t\"ogg\": \"course/en/audio/audio.ogg\"\n},\n```\n\n### Accessibility\nThe media component has two elements that have been assigned a label using the [aria-label](https://github.com/adaptlearning/adapt_framework/wiki/Aria-Labels) attribute: `\"ariaRegion\"` and `\"skipToTranscript\"`. These labels are not visible elements. They are utilized by assistive technology such as screen readers. Should the labels need to be customised or localised, they can be found within the `globals` object in [*properties.schema*](https://github.com/adaptlearning/adapt-contrib-media/blob/master/properties.schema).\n\u003cdiv float align=right\u003e\u003ca href=\"#top\"\u003eBack to Top\u003c/a\u003e\u003c/div\u003e\n\n## Events\nWhenever playback is initiated, the component will emit a `media:stop` event to notify other plugins that make use of audio or video that they should stop playback.\n\n## Limitations\nBrowser | Limitation |\n--------- | :----------- |\nChrome   | No known issues.\nFirefox | No known issues.\niOS/iPad | No known issues.\nAndroid | Firefox 33.1 with Vimeo: 'This video can't be played with your current setup'.\nEdge | No known issues.\nIE11 | No known issues.\n\n## Notes\nAlthough [Adobe Flash Player has now reached End of Life](https://www.adobe.com/uk/products/flashplayer/end-of-life.html) we have left the 'Flash fallback player' in place on the off-chance anyone still needs it and wants to take the risk of using it. The Flash-based video player itself is [hosted on a CDN](https://cdnjs.cloudflare.com/ajax/libs/mediaelement/2.21.2/flashmediaelement-cdn.swf) so no that no Flash file needs to be included in the course output (as many networks/Learning Management Systems now block the .swf file type).\n**Please note**: if you wish to use this method of playback it is entirely at your own risk and not supported by the Adapt Core Team.\n\n----------------------------\n\u003ca href=\"https://community.adaptlearning.org/\" target=\"_blank\"\u003e\u003cimg src=\"https://github.com/adaptlearning/documentation/blob/master/04_wiki_assets/plug-ins/images/adapt-logo-mrgn-lft.jpg\" alt=\"adapt learning logo\" align=\"right\"\u003e\u003c/a\u003e\u003c/br\u003e\n**Author / maintainer:** Adapt Core Team with [contributors](https://github.com/adaptlearning/adapt-contrib-media/graphs/contributors)\u003c/br\u003e\n**Accessibility support:** WAI AA\u003c/br\u003e\n**RTL support:** Yes\u003c/br\u003e\n**Cross-platform coverage:** Chrome, Chrome for Android, Firefox (ESR + latest version), Edge, IE11, Safari 14 for macOS/iOS/iPadOS, Opera\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptlearning%2Fadapt-contrib-media","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadaptlearning%2Fadapt-contrib-media","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptlearning%2Fadapt-contrib-media/lists"}