React to donations in OBS with animation and Piper TTS

Result

This guide builds a reusable donation reaction:

1. DonationAlerts receives a donation.
2. Streaming Hub remembers the current OBS program scene.
3. Three OBS text sources show the donor's name, amount, and message.
4. OBS transitions to a dedicated donation scene.
5. A webcam filter and animation become visible.
6. Piper optionally reads a non-empty donation message.
7. After eight seconds, Streaming Hub disables the filter, returns to the original scene, and hides the animation.

Before you start

You need:

• a connected DonationAlerts account;
• OBS Studio with the WebSocket server enabled;
• a scene that can contain the donation layout;
• Piper only if you want the optional text-to-speech section.

The downloaded script contains the action sequence and signal settings. OBS Slots and their Bindings are project-specific, so you will create and bind them in this guide.

Download the example animation

Use this MP4 as the OBS Media Source while following the guide:

Download Donation_animation.mp4

The animation is eight seconds long. If you replace it with an asset of a different length, update the Pause action to match.

Step 1. Create the Donation Received signal

Create a new automation and select DonationAlerts Donation Received as its signal.

The signal settings can limit an automation to a donation amount range. This makes it possible to create different reactions for small, medium, and large donations. Leave the amount fields empty when the same automation should run for every donation.

In the automation's error handling, set On Step Error to Continue. If one visual or audio step fails, Streaming Hub can still attempt the cleanup steps that disable the filter and return to the previous scene.

Step 2. Build the action sequence

Delete the default Log action and add these actions in order:

1. Get Current Program Scene
2. Source Set Text — donation amount
3. Source Set Text — donor name
4. Source Set Text — donation message
5. Source Set Text — empty-message fallback
6. Scene Transition
7. Filter Enable
8. Source Show
9. Pause
10. Filter Disable
11. Scene Transition
12. Source Hide

The first action stores the current scene in:

runtime.result.obs.program-scene.name

The second Scene Transition will use that Runtime value to return to whichever scene was active before the donation.

Step 3. Prepare the donation scene in OBS

Create an OBS scene named Donation-Scene. Add:

• your webcam;
• the downloaded Donation_animation.mp4 as a Media Source;
• a text source named Donation-Name;
• a text source named Donation-Amount;
• a text source named Donation-Text.

Name the animation source Donation-Animation.

Add a Color Correction filter to the webcam and name it:

Donation-Color-Correction

Set the animation to be hidden by default. Streaming Hub will show it only during the reaction.

Step 4. Create reusable OBS Slots

In Streaming Hub, open the OBS tab. The Profiles view opens first. Create a Default profile if it does not already exist, then use the selector in the upper-left corner to open Slots.

Create these Slots:

Slots keep the automation portable. Each Slot can have multiple Bindings for different OBS profiles, although this guide needs only one Binding per Slot.

Step 5. Connect OBS

If the Binding selectors are empty, configure the OBS connection:

1. In OBS, open Tools → WebSocket Server Settings.
2. Select Show Connect Info.
3. In Streaming Hub, open Services → OBS. You can also double-click OBS in the bottom status bar.
4. Copy the connection values from OBS into the corresponding Streaming Hub fields.
5. Select Mark Connect.

Step 6. Bind the Slots

Return to the OBS tab and select Refresh in the top toolbar. The Binding selectors should now list compatible scenes, text sources, sources, and filters from OBS.

Assign the matching OBS item to every Slot. For the Filter Slot, bind Donation-Color-Correction from the webcam source.

Step 7. Populate the donation information

Configure the three main Source Set Text actions:

These values come from the Donation Received signal contract. You can inspect available contracts for any signal or action in Encyclopedia.

Step 8. Handle donations without a message

When DonationAlerts provides no message, {event.payload.message} cannot be resolved. Streaming Hub deliberately leaves an unresolved contract path as the text event.payload.message, which makes missing data visible during setup.

To show an empty OBS field instead:

1. Duplicate the Source Set Text action for Donation-Text.
2. Leave Text empty. A single space also works if the editor requires a value.
3. Select Edit in the Step Details header.
4. Enable the run condition and enter:

{event.payload.message}==event.payload.message

The left side resolves only when a message exists. If it does not resolve, the expression becomes event.payload.message==event.payload.message, so the fallback action runs and clears the OBS text.

Step 9. Configure the visual reaction

Configure the remaining OBS actions:

For a static target, Scene Transition first looks for a Slot with the supplied name. If no matching Slot exists, it can use an OBS scene with that name. The return transition is dynamic, so it reads the scene name saved by Get Current Program Scene.

Step 10. Test the OBS reaction

Use the selected Donation Received test preset to run the automation without waiting for a real donation. Watch both OBS and Streaming Hub Logs:

• all three text fields should update;
• OBS should transition to Donation-Scene;
• the animation and filter should remain active for eight seconds;
• OBS should return to the scene that was active before the test;
• the animation should be hidden at the end.

Also test a preset where event.payload.message is empty. Donation-Text should be blank rather than displaying the unresolved contract name.

Step 11. Optional: install and configure Piper

Open Services → Piper TTS, or double-click Piper TTS in the status bar.

If you already run Piper separately:

1. Select External Server.
2. Enter the server URL.
3. Connect to the server.

If Piper is not installed:

1. Select Install Piper.
2. Wait while Streaming Hub downloads the package and configures its paths.
3. Enable Start Server on Launch, or use Start Server whenever you need TTS.

The initial installation includes one English voice. To add other languages or voices, download compatible Piper voice files and place them in the directory opened by Open Voices Folder.

Step 12. Speak only non-empty messages

Insert Piper Speak immediately after Source Show and before Pause.

Configure it as follows:

StartInBackground starts playback and lets the automation continue immediately. Queue prevents simultaneous Piper requests from talking over one another.

The condition is the inverse of the empty-message fallback. It becomes true only when the contract was replaced with a real donation message.

Finally, add an Application Audio Capture source for Streaming Hub in OBS so viewers can hear Piper.

Verify the finished automation

Run at least these tests:

1. A donation with a name, amount, currency, and message.
2. A donation with an empty message.
3. Two quick donation tests when Piper is enabled, to confirm that speech is queued.
4. A test started from a different OBS scene, to confirm that the return transition is dynamic.
5. A test with one OBS source temporarily renamed, to confirm that the cleanup steps still run and the failure is visible in Logs.

If it does not work

• No OBS Bindings are available: reconnect OBS, select Refresh, and verify that the current OBS profile contains the expected sources.
• The action cannot find a filter: bind the Filter Slot to the webcam's Donation-Color-Correction filter, not to the webcam source itself.
• The return transition fails: confirm that Get Current Program Scene is the first action and the target is {runtime.result.obs.program-scene.name}.
• The animation stays visible: verify that Source Hide targets Donation-Animation and that error handling continues through the cleanup actions.
• The text field shows event.payload.message: add the fallback action and copy its condition exactly.
• Piper is silent: start the Piper server, select an installed voice, test the service connection, and capture Streaming Hub audio in OBS.
• Speech overlaps: confirm that Queue Mode is Queue.

Adapt it

• Duplicate the automation and use the Donation Received amount filters to create different reactions for donation tiers.
• Replace Color Correction with another OBS filter, or enable several filters in sequence.
• Add a second Source Show action for an image, browser source, or foreground overlay.
• Add a Twitch, YouTube, or another supported Send Message action after the cleanup steps. For example: Thank you, {event.payload.username}!
• Replace the fixed eight-second Pause with a Number variable so the timing can be adjusted from the Variables panel.
• Use different Piper voices for different donation tiers or languages.

Related

• OBS integration
• DonationAlerts integration
• Piper TTS integration
• Pass data between steps
• Use variables and conditions