30:T14c5,md` ### Options

\`duration\`: length of the media in seconds. Defaults to \`1\`. Same as [HTMLMediaElement.duration](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/duration).
\`currentTime\`: current playback time in seconds. Defaults to \`0\`. Same as [HTMLMediaElement.currentTime](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/currentTime).
\`autoplay\`: indicates whether playback should automatically begin. Defaults to \`false\`. Same as [HTMLMediaElement.autoplay](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/autoplay).
\`loop\`: controls whether the media element should start over when it reaches the end. Defaults to \`false\`. Same as [HTMLMediaElement.loop](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/loop).
\`playbackRate\`: sets the rate at which the media is being played back. Defaults to \`1.0\`. Same as [HTMLMediaElement.playbackRate](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/playbackRate).
\`defaultPlaybackRate\`: indicates the default playback rate for the media. Defaults to \`1.0\`. Same as [HTMLMediaElement.defaultPlaybackRate](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/defaultPlaybackRate). Note that setting defaultPlaybackRate has no effect on the play rate, as stated by the standard.
\`delay\`: approximate time in milliseconds between two successive \`timeupdate\` events. Defaults to 200
\`invalidation\`: an optional promise that will dispose of the internal resources if resolved. Defaults to undefined
\`onstep\`: a function that is called on _every animation frame_ while playing the media, and when currentTime is set. It is passed the currentTime as an argument: \`onstep(t)\`. It makes sense to use it to animate the element at every time t. Beware, it's called synchronously and might interfere with the internal timer if it takes time. Defaults to undefined.
\`ontimeupdate\`: a function that is called on _every \`timeupdate\` event_, which occur every \`delay\` milliseconds approximately while playing, and when currentTime is set manually. It is passed the currentTime as an argument: \`ontimeupdate(t)\`. It makes sense to use it to animate the element at a slower rate than whith \`onstep\`. Control the update frequency with \`delay\`. Beware, it's called synchronously and might interfere with the internal timer if it takes time. Defaults to undefined.

### Properties All options can be get and set as properties of the media as with [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement), for example: ~~~js element.loop = false; const t = element.duration; element.currentTime = 3 ~~~ Other properties:

\`paused\`: _read-only_. tells whether the media is paused. Same as [HTMLMediaElement.paused](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/paused).

### Methods

\`pause()\`: pause playback of the media. If it is already in a paused state this method will have no effect. Same as [HTMLMediaElement.pause()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause).
\`play()\`: attempts to begin playback of the media (it will always succeed, contrarily to HTMLMediaElement.play()). It returns a Promise which is resolved when playback has been successfully started (always). Same as [HTMLMediaElement.play()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play).

### Events

\`ended\`: fired when playback or streaming has stopped because the end of the media was reached. Same as [HTMLMediaElement ended event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/ended_event).
\`pause\`: sent when a request to pause an activity is handled and the activity has entered its paused state, most commonly after the media has been paused through a call to the pause() method. Same as [HTMLMediaElement pause event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause_event).
\`play\`: fired when the paused property is changed from true to false, as a result of the play() method, or the autoplay attribute. Same as [HTMLMediaElement play event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play_event).
\`ratechange\`: fired when the playback rate has changed. Same as [HTMLMediaElement ratechange event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/ratechange_event).
\`timeupdate\`: fired when the time indicated by the currentTime attribute has been updated. Same as [HTMLMediaElement timeupdate event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/timeupdate_event).
\`durationchange\`: fired when the duration attribute has been updated. Same as [HTMLMediaElement durationchange event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/durationchange_event).

`31:T1861,function mediatize( that = new EventTarget(), { duration = 1, currentTime = 0, autoplay = false, loop = false, defaultPlaybackRate = 1.0, playbackRate = 1.0, delay = 200, onstep, ontimeupdate, invalidation } = {} ) { // state let _duration, _startTime, _elapsed, _startTimestamp, _requestID, _autoplay, _loop, _playbackRate, _defaultPlaybackRate, _timeupdateElapsed, _timeupdateStartTimestamp; function _init() { // in milliseconds _elapsed = 0; _startTimestamp = undefined; // count _requestID = undefined; } function _stop(stopTime) { cancelAnimationFrame(_requestID); if (stopTime !== undefined) { that.currentTime = stopTime; that.dispatchEvent(new Event('timeupdate')); } else { // force the use of the setter for its side effects // but it's not explicit - we should do better that.currentTime = that.currentTime; } that.dispatchEvent(new Event('pause')); } function _step(t) { if (_startTimestamp === undefined) { _startTimestamp = t; _timeupdateStartTimestamp = t; that.dispatchEvent(new Event('play')); } _elapsed = t - _startTimestamp; _timeupdateElapsed = t - _timeupdateStartTimestamp; if (that.onstep) { that.onstep(that.currentTime); } // dispatch periodic timeupdate events if (_timeupdateElapsed >= that.delay) { _timeupdateStartTimestamp += that.delay; that.dispatchEvent(new Event('timeupdate')); if (that.ontimeupdate) { that.ontimeupdate(that.currentTime); } } if (that.currentTime < that.duration) { _requestID = requestAnimationFrame(_step); //.bind(that)); } else { _stop(that.duration); that.dispatchEvent(new Event('ended')); if (that.loop) { that.play(); } } } // properties Object.defineProperties(that, { duration: { configurable: true, enumerable: true, get: function() { return _duration; }, set: function duration(value) { const first = _duration === undefined; // It seems that HTMLVideoElement rounds to 6 digits. We do the same _duration = Math.max(0, Math.round(Math.abs(+value) * 1e6) / 1e6); if (!first) { // don't dispatch on init that.dispatchEvent(new Event('durationchange')); } } }, currentTime: { configurable: true, enumerable: true, get: function() { // It seems that HTMLVideoElement rounds to 6 digits. We do the same return Math.min( that.duration, Math.max( 0, Math.round( (_startTime + (that.playbackRate * _elapsed) / 1000) * 1e6 ) / 1e6 ) ); }, set: function(value) { const first = _startTime === undefined; _startTime = Math.min(that.duration, Math.max(0, +value)); _init(); if (!first) { // don't dispatch on init that.dispatchEvent(new Event('timeupdate')); } if (that.onstep) { that.onstep(_startTime); } if (that.ontimeupdate) { that.ontimeupdate(_startTime); } } }, paused: { configurable: true, enumerable: true, get: function() { return _startTimestamp === undefined; } }, autoplay: { configurable: true, enumerable: true, get: function() { return _autoplay; }, set: function(value) { _autoplay = !!value; } }, loop: { configurable: true, enumerable: true, get: function() { return _loop; }, set: function(value) { _loop = !!value; } }, playbackRate: { configurable: true, enumerable: true, get: function() { return _playbackRate; }, set: function(value) { if (+value > 0) { if (+value !== that.playbackRate) { _playbackRate = +value; that.dispatchEvent(new Event('ratechange')); // force the use of the setter for its side effects // but it's not explicit - we should do better that.currentTime = that.currentTime; } } else { throw new Error("NotSupportedError"); } } }, playbackRate: { configurable: true, enumerable: true, get: function() { return _defaultPlaybackRate; }, set: function(value) { if (+value > 0) { if (+value !== that.defaultPlaybackRate) { _defaultPlaybackRate = +value; that.dispatchEvent(new Event('ratechange')); } } else { throw new Error("NotSupportedError"); } } }, defaultPlaybackRate: { configurable: true, enumerable: true, get: function() { return _defaultPlaybackRate; }, set: function(value) { if (+value > 0) { if (+value !== that.defaultPlaybackRate) { _defaultPlaybackRate = +value; that.dispatchEvent(new Event('ratechange')); } } else { throw new Error("NotSupportedError"); } } } }); that.pause = function pause() { _stop(); }; that.play = function play() { if (that.currentTime === that.duration) { that.currentTime = 0; } _requestID = requestAnimationFrame(_step); //.bind(that)); return Promise.resolve(undefined); }; // init the state using setters that.delay = delay; // no getter/setter that.onstep = onstep; // no getter/setter that.ontimeupdate = ontimeupdate; // no getter/setter that.duration = duration; that.currentTime = currentTime; that.autoplay = autoplay; that.loop = loop; that.defaultPlaybackRate = defaultPlaybackRate; that.playbackRate = playbackRate; that.dispose = function dispose() { cancelAnimationFrame(_requestID); }; if (invalidation) { invalidation.then(() => { that.dispose(); }); } if (that.autoplay) { that.play(); } return that; }32:[] 2e:{"title":"Mediatize","cells":[{"id":0,"value":"md`# Mediatize\n\n> Enhance an element to use it as a media (video).\n\nOnce \"mediatized\" the HTMLElement will now provide the same API as HTMLVideoElement: you can autoplay, loop, change the current time, change the playback rate... It particularly makes sense if you want to animation your element.\n\nTechnically, the HTMLMediaElement interface will be partially implemented onto the element. The only requirement on the element is inherit from or implement EventTarget. It element is an EventTarget, it's a pure \"timer\" media. But it can be a canvas, an SVG, or any HTML element.\n\nYou can associate your \"mediatized\" element with [videoControls](https://observablehq.com/@severo/detached-video-controls) to get a user interface for the play/pause controls.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":468,"value":"canvas = {\n const ctx = DOM.context2d(160, 90);\n ctx.font = '48px sans-serif';\n ctx.textAlign = 'center';\n\n const draw = t => {\n ctx.fillStyle = `limegreen`;\n ctx.fillRect(0, 0, 160, 90);\n ctx.fillStyle = 'white';\n ctx.fillText(Math.floor(t * 10), 80, 60);\n };\n\n return mediatize(ctx.canvas, {\n duration: 10,\n onstep: draw\n // ontimeupdate: draw // try the difference with ontimeupdate\n });\n\n // example taken from the excellent: https://observablehq.com/@mourner/canvas-recorder\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":509,"value":"videoControls(canvas)","pinned":false,"hidden":false,"mode":"ojs"},{"id":653,"value":"md`Install with:\n\n~~~js\nimport {mediatize} from '@severo/mediatize'\n~~~\n\nCreate:\n\n~~~js\nmediatize(element, options)\n~~~\n\nThe function returns the same element with its enhanced API.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":312,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":6,"value":"md`---\n\n### Credits\n\n_Developed for the [LIRIS M2i project](https://projet.liris.cnrs.fr/mi2/) by Sylvain Lesage._\n\n---\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":9,"value":"md`### CHANGELOG\n\n- 2021-03-18: creation\n\n### TODO\n\n- document .dispose(), and ensure it does all it should (should we remove the API properties and method?)\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":255,"value":"md`### Code`","pinned":false,"hidden":false,"mode":"ojs"},{"id":563,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":20,"value":"md`### Dependencies`","pinned":false,"hidden":false,"mode":"ojs"},{"id":63,"value":"import { videoControls } from '@severo/detached-video-controls'","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W32","stdlib":"1","titling":"auto"}