A Python-powered slideshow generator with steroids

What is Auditorium

auditorium is a Python module for creating slideshows which are ultimately displayed in a browser using the amazing library reveal.js.

With auditorium you don't need to learn JavaScript, HTML or CSS. Everything goes in your Python code, both presentation content and logic.

How it works

auditorium creates a continuous feedback loop between Python and HTML/JavaScript.

  • Every slide in auditorium is a Python method.
  • You can mix up content with logic.
    • Inject variables into the presentation.
    • Receive back interaction events and values.
  • Layout is handled by reveal.js.
  • You only ever need to write Python code.

The basics

Start by declaring a Show instance.

from auditorium import Show
show = Show("Auditorium Demo")

Add a method for every slide, decorated with @show.slide.

def my_slide(ctx):
    # slide content

Finally run the show.

auditorium run []

Some examples

Slide content is added with markdown.

Or directly as HTML.

def example(ctx):
    ctx.header("Some examples")
    ctx.markdown("Slide content is added with _markdown_.")
    ctx.markup("Or <strong>directly</strong> as HTML.")

Static Content

Static content can also be added directly as markdown in the docstring of the corresponding method.

def static_content(ctx):
    ## Static Content

    Static content can also be added directly as markdown in
    the `docstring` of the corresponding method.

Custom layout

More complex layouts can be composed.


You can put custom content in any column...

with ctx.columns(2, 3) as cl:
    ctx.markdown("#### Content")

Dynamic Data

Use dynamic data with two-way binding to add executable Python logic to your presentation.

Hello World!!

def data_binding(ctx):
    # ...
    text = ctx.text_input("dlrow")
    text = "".join(reversed(text)).title()
    ctx.markdown(f"Hello {text}!!")


You can create simple stateless animations with pure Python


with ctx.animation(steps=10, time=0.33, loop=True) as anim:
    ctx.markdown("> ### ." + ("." * anim.current))

Vertical Slides

Vertical slides allow you to create "read-more" like features in your slideshow. They can be skipped on shorter presentations and left for more interested audiences.

Press DOWN instead of LEFT or click the down arrow.

Vertical Slides: Code

def main_slide(ctx):
    # content of main slide

def vertical_1(ctx):
    # content of first vertical slide

def vertical_2(ctx):
    # content of first vertical slide

Vertical Slides: More Info

If you press SPACE instead of LEFT or DOWN the slideshow will cycle through all of the slides in order, including vertical slides.

Show will go down and left automatically as necessary.


Like beamer, pre-styled blocks are available.

Standard block

And its content...

Success block

For happy endings...

Warning block

For hairy stuff...

Error block

When nothing works...

Blocks: Code

with ctx.block('Standard block'):
    ctx.markdown("And its content...")

with ctx.success('Success block'):
    ctx.markdown("For happy endings...")

with ctx.warning('Warning block'):
    ctx.markdown("For hairy stuff...")

with ctx.error('Error block'):
    ctx.markdown("When nothing works...")


Fragments allow to animate elements inside a slide.

The can have different animations as well...

with ctx.fragment(style='...'): # fade-in, grow, ...
    # content

Fragment examples

Here are some of the possible fragment animations.













Dynamically generated graphs with pyplot can be added also very easily.

Monte Carlo Sampling

Samples: 0

Inside: 0

Pi = 0.000

Pyplot: Code

xg = np.random.RandomState(0)
yg = np.random.RandomState(1)

with ctx.animation(steps=60, time=0.5, loop=True) as anim:
    x = xg.uniform(size=anim.current * 50)
    y = yg.uniform(size=anim.current * 50)
    colors = ['green' if xi ** 2 + yi ** 2 < 1 else 'orange'
            for (xi, yi) in zip(x,y)]
    plt.scatter(x, y, s=3, c=colors)
    plt.ylim(0, 1)
    plt.xlim(0, 1)
    ctx.pyplot(plt, fmt='png', height=350)

Going full static

If you only need auditorium for the initial rendering of the HTML, and have no animations or interactive code, you can use:

auditorium render [file] > [output.html]

This will render the slideshow into a static HTML with all CSS and JavaScript embedded, that you can take away and reproduce in any browser, or host on a static file server (like Github pages).


A standard reveal.js theme can be specified at creation time:

show = Show(theme='black')

Or directly as a query string arg:

Markdown First

If your Python code is short and you prefer to author directly in Markdown, you can do almost everything in a Markdown file and insert Python here and there.

Run your slideshow with:

auditorium run []


You can append one show instance right after another, ad-infinitum, to compose larger slideshows from shorter ones.

show_1 = Show("...")
# content
show_2 = Show("...")
# content

It also works directly with file paths, both Python and Markdown.



A demo for the "pure markdown" mode

Static content

Static content can be added with pure markdown.

  • Some markdown content.
  • More markdown content.

And some Python

If you need interaction or advanced features, add a code section with tag [python :run].

Hello World

with ctx.columns(2) as cl:
    text = ctx.text_input("World")
    ctx.markdown(f"Hello {text}")

An instance named ctx will be magically available.


By default local variables created in a Python block are not persisted. If you want to change this, use :persist.

cl = ctx.columns(2)
text = ctx.text_input("World")
# cl and text persist

Hello World
ctx.markdown(f"Hello {text}")
# don't forget cl.end()

Markdown Variables

Persistent local variables are injected into Markdown and can be interpolated inside the content.

Hello World. This is pure Markdown.

```python :run :persist
text = ctx.text_input("World")

Hello {text}. This is is written in Markdown.