Getting Started

Introduction

Welcome to Stream Tool, a Python package for creating a customizable website for with custom macros. With Stream Tool, you can easily build a website, create pages, and add buttons with various functionalities, including integration with OBS using websockets.

Before getting started make sure you have Stream Tool installed.

Although all the commands are written for the console in this tutorial, I recommend following along in a script. You can put build_and_run at the end of your script and run at any point to see your progress. You can also use print() commands to see what the attributes return. This is because of an issue with running build_and_run in the console multiple times which is explained in the footnote to the Running the Website section.

Importing

Make sure Stream Tool is imported. You can import the whole library or just specific modules and functions.

>>> from stream_tool import *

For this tutorial we’ll only need the create_website function, builtin_obs_actions, and Websockets_Auth so we can just import those to keep the namespace clean.

>>> from stream_tool import create_website, builtin_obs_actions, Websockets_Auth

Creating a Basic Website

With Stream Tool imported, to get started, use the create_website function to create a basic website:

>>> my_site = create_website()

This returns an instance of the class Website and assigns it to the variable my_site.

That instance will have an empty website with a blank index page.

Running the Website

When you want to see the current state of the site or are ready to use it you should run the method build_and_run from your Website.

>>> my_site.build_and_run()
 * Serving Flask app 'stream_tool._website'
 * Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:5000
Press CTRL+C to quit

Running this starts the server on your local machine on port 5000. This site can be accessed on that machine at http://127.0.0.1:5000.

The console will tell you this as well. It will also provide a warning about this being a development server. That is just fine for this use which is intended to only be used within your local network.

You can press CTRL + C to stop the server.

You may get an error when running this saying that the port is already in use. In that case you’ll have to use the following code to specify a different port than the default 5000.

The server can also be made available to other machines on the local network and on a different port using arguments or keyword arguments. Host is the first argument and '0.0.0.0' is the host to set to to have this available on the local network. The port is the second argument and can be any valid integer port.

# Using arguments
>>> my_site.build_and_run('0.0.0.0', 6050)
 * Serving Flask app 'stream_tool._website'
 * Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:6050
 * Running on http://192.168.86.124:6050
Press CTRL+C to quit

# Using keyword arguments
>>> my_site.build_and_run(port=6050, host='0.0.0.0')
 * Serving Flask app 'stream_tool._website'
 * Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:6050
 * Running on http://192.168.86.124:6050
Press CTRL+C to quit

You can do this at any time during the tutorial to see what it currently looks like or at the end of a script [1] .

Using The Index Page

We can access and store the saved index page by pulling it from the attribute Website.index_page.

>>> my_index_page = my_site.index_page

Adding Pages

Now, let’s create a new page for our website. Creating a page requires a name to be specified as the first argument. The name will be used in the link to the page. Creating a page returns an instance of the Page class.

>>> volume_page = my_site.add_page("My Page")

Customizing Pages

Oh wait! That’s not a very cool page name, let’s pick a new one. We can change the name at any time with the Page.name attribute.

>>> volume_page.name = "Volume Page"

The page name is what will be used as the url for the page. Since page names cannot have a space in them it will replace it with a dash when it’s set. We can check this by looking at the pages url or name.

>>> volume_page.url
'/Volume-Page'
>>> volume_page.name
'Volume-Page'

Adding Buttons

Buttons can be added to pages to perform various actions. Now, let’s add a new button to our page. It has one required argument of a name for the button. Adding a button returns an instance of the Button class:

>>> my_button = volume_page.add_button("My Button")

Customizing Buttons

We can change the attributes of our already created button to change its text or functionality.

We can change the text the button says by assigning to the text parameter. If no text is provided in the initializing of the button the text is set to the name.

>>> my_button.text
'My Button'

Let’s change the button to say “Volume Up”. We can change the name while we are at it, but that isn’t really used for anything we’ll see.

>>> my_button.text = "Volume Up"
>>> my_button.name = "better name"

The name is formatted similarly to the page names, except it removes spaces and adjusts cases.

>>> my_button.name
'BetterName'

Making Buttons Functional

Let’s add a button with a link to another page. We can edit the button_link attribute of the button. This can be a link to another page or a relative link to this site.

Here’s how we’ll add a button and have it link to the index page:

>>> index_link_button = volume_page.add_button("Index")
>>> index_link_button.button_link = my_index_page.url

This is how we could add a button to link to an external site. Let’s try adding it to the index page.

>>> ext_link_button = my_index_page.add_button("Google")
>>> ext_link_button.button_link = "https://www.google.com"

We can also have the button press execute a python function. Here’s one that would print text on the button press. We have to define a function and then set the attribute button_function to that function.

>>> def print_hello():
...     print("Hello, world!")

>>> my_print_button = volume_page.add_button("Print Hello")
>>> my_print_button.button_function = print_hello

Adding OBS Websockets Integration

If you want to integrate with OBS using websockets, you first need to setup the connection and authentication information. There are 3 variables in Websockets_Auth for this: websocket_host, websocket_port, websocket_password.

These need to be configured with what you have setup in OBS.

If you are running the webserver from the same machine as OBS than the host will be the 'localhost' or '127.0.0.1'. If it is running on a different machine then the one running the web server that machines IP address will be used. This is a string.

If it is running on the same machine the port will be the one that OBS says websockets is using. If it is not the same machine it will also be the same port unless there is port forwarding on that computer. (The firewall may need to be opened up if using a different machine for the web server and OBS)

The port is an integer.

The password is the one set in OBS. It is a string.

>>> Websockets_Auth.websocket_host = "your_host"
>>> Websockets_Auth.websocket_port = "your_port"
>>> Websockets_Auth.websocket_password = "your_password"

You will also need to enable the use of OBS websockets when creating your website. Make sure the authentication is setup before you create the website because this is when the connection will be made.

>>> obs_site = create_website(use_obs_websockets=True)

Buttons can then be linked to OBS actions. For example, let’s create a button to increase the volume of an audio input by 6 dB:

>>> my_obs_button = volume_page.add_button(
...     "Change Volume",
...     button_function=builtin_obs_actions.change_volume,
...     button_function_args=('your_input_name', 6))

We pass the function we want to run into button_function and if there are any arguments for that function it goes in order as a list into button_function_args.

change_volume takes 2 arguments, the audio input to change and the amount of dB to change it by.

Remember to replace 'your_input_name' with the actual name of the input in your OBS configuration.

There are other functions in builtin_obs_actions that can be used in the same fashion. There’s a list in the API documentation here.

What Have We Got?

If you’ve followed along through the whole tutorial you have a lot of buttons now and 2 pages. Let’s run it and see what we’ve got!

>>> my_site.build_and_run("0.0.0.0")
 * Serving Flask app 'stream_tool._website'
 * Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:5000
 * Running on http://xxx.xxx.xxx.xxx:5000
Press CTRL+C to quit

If we visit the site (either one) that shows up in the console, we can see our index page with wonderful links to Google and our Volume page as well as a button to say ‘Hello, world!’

If we go to the volume page we have a button to go back to the index, one that does nothing, one to adjust the volume of a source in obs, and one to say ‘Hello, world!’

You can even try checking it out on another device. Take out your phone and if its on the same network try going to the second address shown in the console. You should be able to control all the same things from your phone or any other device on the network!

Congrats! You made it through the tutorial… or skimmed it… or skipped to the end.

No matter how you got here, for more information on everything, refer to the official Stream Tool API documentation.

But we don’t have to stop the learning yet, we can also do some more advanced macros, let’s try that!