OpenShow is in development right now for use in worship services and other events at a Unitarian Universalist Church. We've tried paid software packages which claim to work, but never found one that was fully-featured and stable enough. OpenShow tries to use advanced code others have written already, as is the custom in Django-land.
These are the core concepts used to make OpenShow work.
A collection of segments (at a concert, you might have a segment for each song being played, for example). A show is assigned a theme, which will be used to style slides being presented.
A segment can have its own set of slides, or include a deck.
A reusable collection of slides, such as the lyrics to a song. Decks are assigned their own theme.
A slide. Right now, they're thinly veiled HTML.
A text box, image, or audio/video clip to be played. These are styled with CSS from the selected theme, and make up the actual content of a Slide.
Themes are written in CSS. TODO: Add a list of standard CSS class names which themes should implement to be compatible with most shows.
Transitions are CSS animations. The editor allows you to specify your keyframes in a relatively intuitive way.
Displays are where slides get shown. This is a separate page to be opened in another broswer window, or used (for example) in an OBS Browser Source.
As of release v0.1.0, OpenShow now has an official Docker container. The container does not serve static files or media. Those will have to be on bind mounts or volumes, so they can be served by some other webserver. In my deployment, I use the official nginx container for this. Both that and the dynamic application are behind a Traefik reverse proxy. docker-compose.yml.example contains a very simplified version of my deployment.
This is just my method, and nothing about OpenShow requires that you use Traefik or NGINX. It's the way I'm familiar with, though, and it works well for me.
Note
This setup guide assumes that your container host is running linux. Any distro with a functional docker-compose should work. OpenShow has not been tested running anywhere other than a Linux host. If you have a working setup on another OS, please open an issue and share notes!
- Save
docker-compose.yml.exampleasdocker-compose.ymlsomewhere on your system. - Edit
docker-compose.ymlto your specification.- Out of the box, the only thing you must change is the value of
OPENSHOW_SECRET_KEY. Set that to a random 50 character string. - Be advised that the default docker-compose file will create a directory
./openshowrelative to the directory containing your docker-compose setup and place the application state within. This includes media files, static files, and the sqlite database.
- Out of the box, the only thing you must change is the value of
- Start up the containers with
docker-compose up -d. - Open a web browser and visit localhost:8080. You should see the OpenShow index, assuming everything worked correctly. OpenShow currently has no authentication at all, so there's no initial account creation necessary.
Now that you have a working instance of OpenShow, the next step is to learn how to use it. In-depth documentation is in progress, but here's a general overview. Refer to the "Concepts" section above for explanation of terminology such as "Show", "Segment", "Theme", etc.
- Click "Slides" to enter the slides module. Other modules are not essential to most installations.
- Before you start creating slides, you'll need a theme. Create one by clicking on the "Themes" tab, followed by "New Theme". Set a name and submit it.
Note
The current theme editor dates back to the initial prototype of OpenShow, and is due for a complete rewrite. This isn't the final form of this interface (thank goodness!).
- The unlabeled text box below the preview winodw is where you put CSS rules which make up your theme. If you're not experienced with CSS, or if you just want a somewhat sane place to start, copy the contents of
example-theme.cssfrom this repository into that text box and click "Submit". - Next, you'll need a display. Click the back button on the left side of the header to return to the slides index, select the "Displays" tab, and click "New Display". Enter a name for your display and submit it.
- Click the link to open that display in a new tab, then move that tab to a new window. Put it somewhere that you can get to it easily.
- Click the back button to return to the slides index. You'll automatically be on the Show page. Click "New Show", enter a name, and submit it.
- Welcome to the show editor! Now, you'll want to select the theme you just created. Click on "Set Theme", select your theme in the resulting dropdown, and click "Submit".
- Next, create a segment using the plus button in the left sidebar. Enter a name and click the checkbox.
- You'll see a box in the sidebar labeled with the name of your segment. Click on the smaller plus button near the bottom of the segment to add a slide.
- Click on the slide. This will open your new slide for editing.
- The bottom left panel of the editor contains options for changing the properties of the entire slide. You can leave all of that alone for now and click "New Element".
- Enter the CSS class which you would like to apply to your new element. This should be a class (or set of classes) which is defined in the CSS you placed in the theme in step three. Click the checkmark button.
- You should see placeholder text appear in the preview area saying "Double-click to edit". Follow that direction and add some text to your slide element. Press ctrl+enter or click the checkmark to save the content.
- Click the back button again, which this time will take you to the presenter view for your show. In the right sidebar, there's a gear button. Click that, select your display in the list, and click the checkmark. That sets this Show object to send slides to your display.
- In the main body of the presenter view, you'll see a thumbnail for the slide you just created. Click on it! The slide you created should appear in the browser window where you opened your display.
Congratulations! You've just displayed your first slide using OpenShow! Hopefully that gives you an idea of the UI. Many pieces of the editor have function descriptions built in - otherwise, more documentation will be forthcoming. Feel free to file an issue if you have any question, even if it's probably not a bug.
OpenShow uses honcho both in development and production, as we need a separate worker process for video transcoding. In production, you should almost certainly use the docker container, but here's how you set up a development environment:
- Clone this repository
- Create a python virtual environment:
python3 -m venv venv - Activate the virtual environment:
source venv/bin/activate - Install requirements as usual:
pip install -r requirements.txt
Note
If you want your development instance to transcode media objects, you'll need to install ffmpeg as well. Everything else will work without it.
- Run the server:
honcho start -f Procfile.development
Once you have this running, you can navigate to localhost:8030 in your web browser and start messing with OpenShow. The development server port can be changed by editing Procfile.development to suit your needs.