vue-perfectlooper
A perfectly looping image sequence player with fullscreen capabilities, built with mobile performance and keyboard accessibility in mind.
Demo: https://admiralpotato.github.io/vue-perfectlooper/
This project's primary objective is to allow seamless playback of short, perfectly looping animations in the browser, at the highest possible visual quality, optionally in fullscreen mode. Providing frames at the full resolution of your intended output device with no visible compression artifacts is strongly recommended.
Viewer friendly features:
- Very low CPU usage while playing
- Timeline scrubbing
- Frame advance & reverse
- via buttons for mouse and touchscreen users
- via keyboard left & right arrows when any element of the player has focus
- Fullscreen ability
- there's even been effort put into making this sorta kinda work on iOS
- iOS Safari interactivity DangerZone™ avoidance!
- there's even been effort put into making this sorta kinda work on iOS
Developer friendly features:
- It's responsive; adapts to any element you put it in
- It's a one file module; even contains its own CSS
- Customizable frame path options
Install and Usage
Compiled .vue file flavor:
npm install --save vue-perfectlooper
myLoop.vue:
<template> <vue-perfectlooper v-bind="loop"></vue-perfectlooper></template><script> import VuePerfectlooper from 'vue-perfectlooper'; let amazonCDN = 'https://aws-website-videonuclearpixelcom-tgl8t.s3.amazonaws.com/content/'; export default { components: {VuePerfectlooper}, data: function(){ return { loop: { "id": "crusaderarts_red_room_tribute-24", "poster": amazonCDN + "crusaderarts_red_room_tribute-24-preview.jpg", "src": amazonCDN + "crusaderarts_red_room_tribute-24-1920x1080/", "frames": 24 } } } };</script>Vanilla Javascript
In your HTML:
Providing frames to the player
All configurations require the following parameters:
-
id: this is the primary key by which the source images are cached in-memory to prevent unnecessary HTTP traffic in the case that the player is spawned and destroyed more than once in a session after initial load; also used as the analytics identifier in the scenario that the vue-analytics plugin has been installed. -
poster: a path to the preview image which is displayed before the user chooses to play the animation.
There are currently several different formats which may be used to provide frames to the player:
With the default structured file name sequence
All properties specified here are required for this configuration.
In this example, the required file structure is:
http://cdn.example.com/loops/electric_flower-preview.jpg
http://cdn.example.com/loops/electric_flower/(0001.jpg ~ 0048.jpg)
With a custom structured file name sequence
There are additional configuration parameters that can be specified for a structured file name sequence. Note the addition of the following properties: sequenceTemplate, startIndex, prefix, suffix
In this example, the required file structure is:
https://cdn.example.com/loops/infernal_recursion.jpg
https://cdn.example.com/loops/infernal_recursion-(00 ~ 23).png
With non-sequential image addresses
In this example, there are no expectations of asset organization, as each frame path is completely specified explicitly; As a side effect of this, the number of frames does not need to be specified in this configuration.
With an Imgur Album ID
In this example, the only two required attributes are id and srcImgurAlbumId. The poster attribute is not required, as the Imgur Album's cover image can be used. If the poster attribute is passed, it will be displayed before the AJAX request for the album's frame list returns.
It is recommended when hosting image sequences at Imgur, that you upload only PNG sequences; Imgur will both host the original PNGs, as well as automatically generate JPGs at multiple resolutions that may be used for quality presets in a future version of the player. By default, the player uses Imgur's highest quality generated JPGs for playback, which are almost completely without visible compression artifacts. Uploading PNGs also comes with the benefit that you can configure the player to load and play the original PNG sequence, in the case that Imgur's highest quality JPGs did not meet your quality requirements.
Imgur Album ID "gotchas"
- Choosing to use the Imgur Album ID method causes the player to fire an AJAX request to
https://imgur-api-readonly.glitch.me/and wait for a response before it will become interactive - so there may be a 0.25sec ~ 5sec delay before thecoverand frame paths load. - It can be tricky to correctly upload PNG sequences in their correct order to an Imgur album, so you may need to rearrange your frames in the album after they are all uploaded. The frames are played back in the order they are listed in the Imgur album. Always test that your animation plays back correctly before viewing it in fullscreen or sharing it with others, to avoid optically triggered seizures.
Imgur Album ID minimal
Imgur Album ID with poster display before ajax load, and forced load of original PNGs
Other Options
You may configure the player with these additional options:
fps: Sets the framerate of image sequence playback. Default is 24.aspect: Explicitly set the aspect ratio of the player, overriding and ignoring the aspect ratio of the poster image and animation images. This will also cause the player to display at the desired size even before the poster image has loaded. This value can be calculated asheight / width. Default value is automatically calculated as soon as the poster image is loaded, at which point the player will be displayed.