Create interactive screencasts inside Jupyter Notebook that anybody can play back
Create interactive screencasts inside Jupyter Notebook that anybody can play back.
Ever wanted to offer someone a hands-on "live" demo in Jupyter Notebook? Using Graffiti you can add floating tips along with optional recorded movies anywhere in your Notebooks. Demonstrate whatever you want, highlight what's important-- all narrated by you! Since the movie plays back in and on the Notebook, the viewer can pause any time, dive into your code and try things out exactly as you had them when you were recording, and then resume play.
Yes, Graffiti is maintained and kept up to date by its author. Please file issues as you see them or submit PRs. It's most recently been updated for security and to eliminate lodash dependencies, on January 2, 2023.
** Update 1/11/2024: Graffiti has been upgraded to run in Jupyter Notebooks V7, but in "classic" mode. You will have to run your notebooks in Classic mode to use Graffiti until it gets completely rewritten for JupyterLab. I am not intending to make that update unless I hear back from the community that it's desired. **
Please wait about 30 seconds for the demonstration to spin up at mybinder.org. (Thanks to the folks at MyBinder for this awesome service).
No, it only works in Jupyter Notebook classic. It would be quite complex to port to Lab as it has an entirely different internal API. However, if anybody in the community wants to see a port and collaborate, please reach out.
You can also visit the User Manual for more detailed instructions on how to use Graffiti.
You can skip installation entirely if you want, by using the Binder
demo link above. Just upload whatever Notebook you want to add
Graffiti to the demo Jupyter Notebook server, activate Graffiti
(see below), make some recordings, and then download the
jupytergraffiti_data
folder along with your Graffiti-ized Notebook
from the binder Notebook server. To make this easier, we've installed
nbzip
into the Binder demo server. Just go to the server's tree,
visit the jupytergraffiti_data
folder and click the folder download
link. For more details on how this works you can refer to nbzip
's documentation.
You can then commit the jupytergraffiti_data
folder and your
Notebook to your own github repo and set up a link to it on Binder to
share your Graffiti without requiring that the recipient have Graffiti
installed.
Uploading and downloading to/from Binder isn't optimal of course; it's probably better to get Graffiti going on your own computers.
There are four ways to install Jupyter Graffiti: using pip or conda, using a Python library, using a Docker image, or installing a plugin into your Jupyter Notebook server.
pip
or conda
(Easiest Option)Just do:
pip install jupytergraffiti
or
conda install -c willkessler jupytergraffiti
This assumes you have pip
or pip3
, or conda
as well as Jupyter Notebook, already installed.
PLEASE NOTE: Due to changes in Jupyter, the inline terminals will
not work with any version of Jupyter less than 6.1.6. Please run:
conda update --prefix ~/anaconda3 anaconda
and conda upgrade jupyter
to ensure that you have
the latest version, which at the time of the last update to this README is v6.2.0.
Make sure to install Docker on your system first (unless you've already installed it).
Then enter this command in a terminal on your computer:
./jupytergraffiti/build_and_run.sh
This will build and start up a Docker container running the Jupyter Server and the Jupyter Graffiti extension, with the container's home directory being mounted where your Jupyter Notebook(s) are located, and serving Notebooks over port 8888.
The advantage of using the Docker container is that Jupyter Graffiti
is always loaded automatically, so you don't have to execute import jupytergraffiti
in the Notebook just to play back Graffitis (but
you will need to run it to access the Graffiti API).
using the Docker container also ensures you're running a recent version of Jupyter Notebook.
Take a look at the output of the Jupyter Server running in the
container. It has the secret key you need to be able to surf to the Dockerized
Jupyter server. The output will look something like this (but note
that the Jupyter Server login token will change every time you run build_and_run.sh
):
Copy/paste this URL into your browser when you connect for the first time,
to login with a token:
http://(b13ba2b482e9 or 127.0.0.1):8888/?token=e58a08f167881500e207ff9be05ad57ffe00e3457e54017c
What this is telling you is to surf to
http://localhost:8888?token=e58a08f167881500e207ff9be05ad57ffe00e3457e54017c
to access the Jupyter Server with the Graffiti extension installed and
running.
The Docker container will serve content out of port 8888. If you already have
something (e.g. another Jupyter server) running on this port, pass a different port to
build_and_run.sh
like so:
./jupytergraffiti/build_and_run.sh 8889
Note: if you specify a different port, the Jupyter Server output
containing the secret key will still show port 8888, because
internally it still uses port 8888; via Docker port mappings, we
have remapped 8888 to the port you specify. In the example above,
therefore, you would need to access the server at:
http://localhost:8889?token=e58a08f167881500e207ff9be05ad57ffe00e3457e54017c
.
Note: Inline terminals do not seem to work within the Docker container setup, probably due to permission levels.
Note: Before using this method, you may need to Trust your
Notebook. This is because Jupyter Graffiti is mostly written in Javascript,
and by default, if the Notebook you're adding Graffitis to was not
created by you, Jupyter Notebook will not "Trust" it and will not run
externally loaded javascript code, for security reasons. To Trust a
Notebook, click File...Trust Notebook
before running the import
command below.
git clone
this repo in the same directory where you keep the Notebook(s) you want to add Graffiti to.import jupytergraffiti
If everything works, you will see a button labelled "Activate Graffiti" in your menu bar.
If you don't see this button appearing, use Kernel... Restart and Clear Output
first, then try running import jupytergraffiti
again.
Once you see this message, you can "Activate Graffiti" on a Notebook to begin creating Graffiti. The User Manual has many details on how to create Graffiti.
Special Note : if you are adding Graffitis to Notebooks that do not reside in the same folder where you cloned this repo, then you must :
jupytergraffiti_data
directory in the folder where you cloned this repo (mkdir jupytergraffiti_data
).jupytergraffiti
folder in this repo, and to the
jupytergraffiti_data
folder alongside where you cloned this repo.This will permanently install the extension in your computer's installation of the Jupyter Server (although you can always disable it if you want to). This means the extension will always be available whenever you start up your Jupyter server. To install the extension:
cd jupytergraffiti
jupyter nbextension install graffiti_extension --symlink --user
jupyter nbextension enable graffiti_extension/main --user
cd ..
You may need to restart your Jupyter server to get the extension to load, although usually that's not required.
If you need to disable the Graffiti plugin for some reason, you can easily do it.
To disable the plugin:
cd jupytergraffiti
jupyter nbextension disable graffiti_extension/main --user
cd ..
Then restart your Jupyter server.
When you import jupytergraffiti
you get immediate access to
functions you can use to control Jupyter Graffiti from Python. Some
of these are utility functions, and others can be used to control
recordings playback. To use them, simply run the Python functions in your
Notebook's cells (note: the API only works with the Python kernels at this time).
You can also play any Graffiti recording back using Python code. This could be valuable, for instance, after a student has failed several times to make some code work; you could watch for this situation in your testing code, and offer to play a hint recording. Or, if a student's code passes all tests you can start up a recording prompting them to go on to the next exercise.
In the next version of Jupyter Graffiti you will be able to automatically transcribe your spoken audio into subtitles that scroll along with the movie.
Make a Copy ... of a Notebook should copy the recordings to a new Notebook recording ID.
Author/Maintainer:
Will Kessler
github: willkessler twitter: @atlas3650
Advisors: