How do we want to include images and videos in the docs

[MarcSkovMadsen]

I would like to discuss and learn the strategy for including pictures, videos and other heavy assets not used by the code in the Panel in particular and HoloViz projects in general.

Questions

1. Should assets like images, data and video be included in the repository?

• pro: easy to include, easy to version
• cons: makes the repository heavy to git clone for contributors and for ci/cd.

2. Do we want to include videos in the docs?

• pro: we can illustrate interactivity (like templates, full apps, playwright, dask etc.)
• cons: the docs become less useful as interactive notebooks. Videos take time to create and maintain.

2.1. When do we want to include videos in the docs?

2.2. If we include videos should we do this as .gif or .mp4?

• pro: the advantage of .gif is that they autoplay
• cons: the disadvantage of .gif is that they are (much) larger than .mp4

Motivation

I just git pull'ed a branch from Panel and I can see that a lot of the pictures (and gifs?) I've included in some PRs are now a part of the repository

I thought they would be moved to a CDN? As far as I can see some of the .gifs have also been converted to .pngs?

@droumis @philippjfr ?

[MarcSkovMadsen]

My recommendation

Regarding 1. I recommend we don't include assets in the repository. I really like having a repository that is fast to git clone. I've had repositories that took minutes to git clone and its not a nice user experience and also makes your ci/ cd awfully slow.

Regarding 2. I recommend we do want to include videos. And the guiding principle is that they should help the user in a way not possible with code or a static picture.

[philippjfr]

I think we should include images in the repo where it makes sense and host most gifs/videos on the CDN. This is what I did in your streamlit PR, the total size of all the images I added was <50 KB (the slides screenshots should be removed). Assets in the repo are easier to keep in sync and as long as they're small won't have a significant impact.

I don't have strong feelings about gifs vs videos but so far we've always used gifs.

I did not convert any of your gifs to images.

[droumis]

I dislike the use of the CDN for assets. It's a pain for fast-changing docs. I guess it makes sense for a small number of large videos/gifs that don't change often.

In general, I think the very selective use of videos/gifs can convey a concept that's particularly complicated to show in a static image or interactive plot (like a sequence of click-through events), but I don't think they should become the default way we convey information.

[maximlt]

It's a pain for fast-changing docs

Managing the CDN is going to become even more painful when we have docs versioning set up 🙃 But I don't think there's really a way around that, some assets are just too heavy to be committed to the repo.

I'd be interested in us sharing experience on how to create good quality and small size content (screenshots, GIFs), I've struggled with that in the past.

I would avoid GIFs and videos as much as possible in the docs since they aren't very easy to update.

[MarcSkovMadsen]

We need a ScreenRecorder component @maximlt . Like Streamlit has.

• You can add it to a layout.
• It can be activated via a button
• You can configure it to produce either .mp4 or .gif
• You can configure it to rescale the image to some width x height format
  • Optionally you could make it change the window size to that width x height format
• You can optionally configure it to compress the video
• The video should be automatically downloaded or made available for download
• You can use the recorded .mp4 or .gif in Python for your AI model. Its available in a parameter.
• Optionally you can specify an intro and outro video to prepend and append to the recording if you want for example a Panel logo intro and outro. Some transition between videos could be added.

That would cover my workflow.

[maximlt]

I wa referring to Desktop/CLI/web app tools and practices.

[MarcSkovMadsen]

Yeah. But we still need a ScreenRecorder and AudioRecorder if we want to enable users with machinelearning and Generative AI use cases. Just like Gradio.

[maximlt]

Yep. But that's a separate request ;)

[ahuang11]

cons: the disadvantage of .gif is that they are (much) larger than .mp4

I think they can be comparable if you use a tool like gifsicle to optimize the GIF.

[philippjfr]

Indeed, I optimize all gifs we upload with gifsicle.