Hand Siteswap Documentation and Example browser

[aditya95sriram]

Hello JugglingLab community 👋

@JigyasuJuggler recently contributed the Hand Siteswap feature to JugglingLab. Over the past couple weeks, I (along with JigyasuJuggler) have been working on a project (link to repo) aimed at making this feature more accessible and widely known. We would like your feedback and comments on the project and ideas on how to improve it.

Overview

A demo of the project is currently hosted on Github Pages (demo). The project consists of two main sections - Documentation and Examples.

Documentation (link)

Currently the documentation exists as a PDF file of a presentation which isn't super accessible and not to mention, fairly static. We aim to port this over to an HTML webpage. Currently there are a couple pages up already but it's far from completion (compared to the PDF).

Examples (link)

In this section I aim to build an Example catalog/browser of sorts (currently focusing on HSS examples), which would ideally help jugglers locate new patterns by means of tags/filters. Being a rookie juggler myself, this is where the community's feedback would be crucial.

Current roadmap

• Complete documentation porting (match the contents of the PDF)
• Do not fetch GIFs from the JL GIF server each time, instead include GIFs (probably converted to MP4s) as a part of the repo/webpage
• GIFs vs MP4s performance comparison
• Improve search UI

Screenshots

(its normal for some GIFs to not render properly sometimes)

[aditya95sriram]

@jkboyce we had a couple questions for you:

Hosting on jugglinglab.org

Would you like to host this webpage on jugglinglab.org? In case you're curious about the specifics, the webpage is statically generated webpage (using Docusaurus) and doesn't require any server side code.

Allow tags field in jml spec

Currently the examples are pulled in from a jml file (after being converted to json by a python script). Since tags are indispensable for filtering through tons of patterns, I added in a custom field tags=comma,separated,tags right after the title field. This breaks the usability of the jml files in JugglingLab, which isn't ideal.

I see two ways of dealing with this:

1. Allow a tags field either as a part of the body of the <line> tag or as an additional xml attribute alongside notation=siteswap.
2. Read in examples from a separate file/database (I think the convenience of populating the example catalog just from a set of jml files is quite cool and would be lost in this method).

[jkboyce]

Hi @aditya95sriram , I like your idea for an easy way to search, find, and view patterns from the database of patterns.

Ten years ago we had something called jugglewiki, which was a way for people to add pattern animations to a wiki (it was based on Mediawiki) so that others could view them. The viewer was an applet version of Juggling Lab running in the browser. It was very popular until it fell into disrepair (mostly due to spam, we did not require sign-in to edit which was probably a bad idea), and then browsers started dropping java support so the applet version of JL didn't work any more. I still have the last snapshot of the JuggleWiki database from April 3, 2011 when I closed the site down. One thing I've been meaning to do is parse through all those old pages and extract the animations into JML pattern lists.

Anyway I digress. What Jugglewiki showed me is how much people get involved if it's easy to see and create content. I think your site idea would be a great way to do that -- with animations that could be searched and viewed. I could easily host it at jugglinglab.org. I'm using Google Cloud so it supports Java, Python, etc. on the server if needed. It's also straightforward to pull the animations from the storage bucket used by the animation server. It's a relatively simple hash function that goes from the pattern config string (pattern=5;hss=4 etc.) to a GIF url.

Meta data for patterns is a great idea. I've been thinking about an <info> element that would contain free text for a pattern or patternlist: Description, tips on how to juggle it, author credits, etc. The <info> element would occur at the same level as <title>, and tags could be an attribute. Something like:

<line display="Around the pair" notation="jml">
<pattern>
<title>Around the pair</title>
<info tags="3 balls,intermediate">
This is a fun pattern, similar in difficulty to Mills Mess. It looks great with LED balls.
</info>
<prop type="ball"/>
<setup jugglers="1" paths="3" props="1,1,1"/>
...
</pattern>
</line>

For a patternlist item that isn't a JML pattern, I think the cleanest thing would be to make the <info> tag a child of <line>. Like:

<line display="55050 (the snake)" notation="siteswap">
pattern=55050
<info tags="3 balls">This is good practice for 5</info>
</line>

XML supports mixing PCDATA and other elements so this will work fine. I'll have to think about the UI for how to see metadata and set it within Juggling Lab; that's a separate issue.

Another thought: Next to the animation it would be nice to offer a download link to a JML file -- either the patternlist it came from, or just the pattern itself. That way if a user wanted to get a closer look it would be easy.

Also you mentioned mp4 animations. That may be something to consider, I haven't thought about the pros/cons. GIF playback is often kind of choppy in the browser, but at the same time the browser can support many GIF animations at once. I haven't experimented with the <video> tag to see how well browsers perform with many animations on a page. Have you tried it?

[aditya95sriram]

Appreciate the encouraging response @jkboyce 😃

Thanks for the interesting JuggleWiki anecdote, I didn't know about it. It reminded me of the fact that the current example catalog isn't super collaborative. The only way to add examples would be to include more JML files in the source code (probably via a PR to the repo).

I'm currently in the process of comparing the performance difference between GIFs and MP4s, but my impression is that even with 12 GIFs, my browser (Firefox) seemed to be struggling a bit. Nevertheless, I'll get back to you with a proper comparison.

Would be nice to have this hosted on jugglinglab.org. However apart from saving some (mostly automated) preprocessing I don't see a big advantage of using the storage bucket thing you mentioned. Just curious, how hard is it to make the GIF server return MP4s?

I forgot to mention, but currently jml2json.py ignores the patterns that are not notation=siteswap (i.e., JML patterns) mainly because the GIF server doesn't support those patterns (am I mistaken?).

JML downloads is a nice idea, exactly the sort of feedback I was seeking. It shouldn't be too hard to implement. Which do you reckon is more convenient for the user, downloading just the single pattern or the pattern list?

Additionally, I did have plans to include an ℹ️ button for each example with all the required inputs to reproduce the pattern in JugglingLab. Diving into details, I imagine a convenient workflow would be to use a "Copy Inputs" button on the webpage and then paste it into JugglingLab's pattern field, which would then detect the mutliline input and automatically split it into the corresponding fields.

In terms of the XML syntax for metadata/tags, I don't have any strong opinions and would be fine with whatever you decide.

[jkboyce]

Ok great, I'll look forward to hearing what you discover about GIF vs MP4 playback. MP4s (H.264 codec) are easy to generate from the animated GIF using ffmpeg. This works fine:

ffmpeg -i 3.gif -movflags faststart -pix_fmt yuv420p -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" 3.mp4

I haven't tried running ffmpeg on Google Cloud but it should probably work. If not there are some Java libraries that can encode MP4/h.264 directly; I could just make MP4-saving a feature of Juggling Lab.

For displaying in the browser this works:

<html>
<p>Here is an animation</p>
<video playsinline autoplay muted loop width=200>
    <source src="3.mp4" type="video/mp4">
</video>
</html>

For the back-end store for the videos/GIFs, there are several options but for the purposes of creating the site to view the videos, they are all the same: Each video has a unique URL to access it. For coding it you could just start with a big directory filled with GIFs/MP4s and when we deploy it to jugglinglab.org we can think about storage.

Re: downloading JML patterns or patternlists, I might start with patternlists since that will be easier to implement. As you parse through the patternlist files you can just remember the file it came from. We will want to host the patternlist files on jugglinglab.org as well so there is an easy download link. For individual JML pattern files there would be additional work to create these files for each line in a pattern list; not a big problem but extra work nonetheless and doesn't need to be part of the MVP.

There is a gap right now in that the GIF server can't handle JML patterns, as you say. I never created a way to communicate JML to the server; it won't fit in the URL. This is a separate question though and I don't know how important/useful it would be to solve it.

If this as a deployed site on jugglinglab.org, what is your vision for how it would be updated? Two things would cause an update: A change in the pattern files, or a change in Juggling Lab (better rendering for example). I envision some kind of script running on my local machine that would: (a) read in all pattern files, (b) generate animations for new/changed patterns, (c) upload new/changed animations to the cloud, and (d) generate a set of pages and config files for hosting -- which I would deploy to jugglinglab.org. Does that sound about right? Later some or all of those functions could migrate onto the server, but I'm thinking in terms of minimum viable product.

[froudaut]

I played a little with HSS and it works quite well. It is thus really easy to demonstrate the multi-hand basic cascade/fountain as described by Polster. For sure it will be great to be extended with multiplexes in OSS.

[aditya95sriram]

Hi, just to be clear, are you suggesting that this should be included as a part of the HSS documentation material?

[froudaut]

I haven't seen ? Is it a question for me ? No forget it, it was just a remark but indeed It was not probably in the correct thread. I have added and described a little more this in another thread.