Minimalistic YouTube / Imgur / SoundCloud Looper & Playlist Manager
Switch branches/tags
Nothing to show
Clone or download

README.md

pls.watch: The Minimalistic Media Looper

Build Status

Create shareable loops and playlists using simple URL tokens.

A snowball of JavaScript antipatterns that turned into an avalanche of features.
Supports YouTube for video (with playlist import), Imgur for images (with gifv support) and SoundCloud for audio.

Deployed at https://pls.watch

Table of Contents

Background

Scratching own itches.

At the time YouTube did not provide any way to specify end timestamp when sharing a link to a video.
The amount of distractions and advertisements on third party sites that provided this functionality was abysmal.

Out of frustration, pls.watch was born as a clean way to:

  • share specific fragment of YouTube video
  • display content without any distractions such as related videos or ads
  • create playlists with mixed content from YouTube, Imgur (image/gifv) and SoundCloud (audio)
  • guarantee backward-compatible API to create clean permalinks (see URL Parameters)

URL Parameters

The most basic loop is one video with optional range:

#v=<videoId>[&t=<start>[;<end>]]

Time format is 1h2m3s or just a number of seconds.

YouTube

YouTube-compatible syntax is also supported, enabling use by a simple domain swap in URLs: ?v=<videoId>[[#|&|:]t=<start>[;<end>]]

Advanced Loops

A YouTube video can have more than one interval. Intervals are chained with the + sign:

#v=<videoId>&t=<start1>;<end1>+<start2>;<end2>+...

To chain intervals from multiple videos just append another &v=(...) at the end of URL:

#v=<videoId1>&t=<start1>;<end1>+<start2>;<end2>&v=<videoId2>&t=<start3>;<end3>+<start4>;<end4>`

Playlist Import

To generate v=(...) items from <playlistId> and start autoplay from <n>-th element:

#list=<playlistId>&index=<n>

YouTube URLs are supported transparently: if <videoId> is inside of the playlist specified by <playlistId> on <n>-th position, it will be deduplicated:

#v=<videoId>&list=<playlistId>&index=<n>

If URL already had some videos <n> will be recalculated.

Override Video Volume

To cap YouTube sound volume at a preferred level (global setting):

&volume=<level>

Level is a number between 0 (muted) and 100 (max volume).

Override Video Quality

To cap YouTube quality at a preferred level (global setting):

&quality=<level>

Current list of available levels can be found in YouTube Player API Reference.

Override Playback Rate

The default playback rate is 1, which indicates that the video is playing at normal speed. Playback rates may include values like 0.25, 0.5, 1, 1.5, and 2. It is a global flag (sets speed of all YouTube videos in playlist).

&speed=<rate>

Current list of available playback rates can be found in YouTube Player API Reference.

Imgur

By default image is displayed forever (useful for GIFs). A slideshow can be created with simplified t parameter:

#i=<imageId>.jpg[&t=<displayTime>]

Example: https://pls.watch/#i=lkD38.gifv&t=3&i=cJjBEQP.jpg&t=1s&i=vo9DPpp.gif&t=3s

Note: GIF intervals are automatically rendered as GIFV.

SoundCloud

Single track interval:

#s=<user>/<sound>[&t=<start>[;<end>]]

Example: https://pls.watch/#s=sacredbones/pharmakon-body-betrays-itself&t=0s;17s

Playlists (sets) are lazy-inlined on first play:

#s=<user>/sets/<set>

Example: https://pls.watch/#s=erasedtapes/sets/erased-tapes-collection-iv

Any External URL

Generic HTML5 Player

Similar to YouTube Player - main difference is format for videoId.

Currently, to be detected, videoId has to begin with http and end with: .mp3, .mp4, .ogg, .ogv or .webm.

Example: https://pls.watch/#v=https://vt.tumblr.com/tumblr_npa1dkYP1U1urdxm4.mp4&t=4s;5s

Generic Image Player

Similar to Imgur Player but if videoId starts with http it loads the URL and naïvely believes it is an image.

Example: https://pls.watch/#i=https://ipfs.io/ipfs/QmYHNYAaYK5hm3ZhZFx5W9H6xydKDGimjdgJMrMSdnctEm

Global

Random Mode

&random

This parameter will force playback of all intervals in semi-random order (normalized random: current interval will not be played twice in a row).

Playlist Editor

&editor

This parameter will force playlist editor to be visible from the start.

Keyboard Commands

Press ? to toggle help screen listing available shortcuts.

Known Issues

Autoplay does not work in Google Chrome/Chromium

Chrome made the decision not to allow autoplay of video/audio content unless muted, to prevent annoying webpage content. There is no fix for this, but every user can opt-out and restore autoplay by opening chrome://flags/#autoplay-policy, changing it to No user gesture is required and restarting the browser:

enabling autoplay in Chrome

Playback pauses when tab is not active in Google Chrome/Chromium

The fix is the same as above (change chrome://flags/#autoplay-policy). See issue #151 for historical context.

Companion UserScript

There is a simple UserScript that adds a button on supported pages to open current resource in the app.

Installation

Click to install: https://pls.watch/pls.watch.user.js

It may require preinstalled browser extension:

Examples

YouTube

Imgur

SoundCloud

Contribute

Ideas and bug reports are most welcome.

License

The pls.watch itself is released under CC0 Public Domain Dedication.