Help

Everything in PNGTuber Studio, section by section. The same information ships with the app in its docs folder.

1. Quick start

1. Run PNGTuber Studio once. It creates a PNGTuber Studio folder inside your Pictures folder.
2. Put your avatar in its own folder inside it, for example Pictures/PNGTuber Studio/bob/, using the file format below.
3. Run the app again. A single avatar is found and loaded automatically. With several avatars, press Esc, open the Avatar tab, and pick a folder with the Change button.

2. Avatar files

One folder per avatar. Inside it, one folder per emotion. Each image just has to end with its state letter:

bob/
  neutral/A.png
  neutral/B.png
  neutral/C.png
  neutral/D.png
  angry/A.png
  angry/B.png

Longer names work as long as they end with the letter: AngryA.png and bob-angry-1B.png are both fine. The letter must be a capital so ordinary files like banana.png are not mistaken for frames; a lone letter like a.png may be lowercase. Only .png images are used.

Missing states are fine. An emotion with only A and B stays visible while blinking, and A alone gives a static avatar. Files ending in _small.png are lighter copies of the same frame, used when Image size is set to "small when available".

3. The window

The window's background is transparent: everything that is not the avatar stays invisible to OBS. Move it by its title bar and resize it by dragging any edge; its size and position are remembered and restored on the next launch. The avatar keeps a clear strip at the bottom of the window so the control bar never overlaps it.

Move the mouse into the window (while it is focused) and a control bar appears along the bottom edge with the two mic sliders and a Settings button. Move the mouse away and it vanishes, so a cropped OBS capture never sees it.

4. Settings, tab by tab

Press Esc to open the panel; Tab cycles the tabs. Every change saves the moment you make it (watch for the saving and saved flashes near the buttons), and every row has a small i marker whose tooltip explains it. The Reset button restores default tuning after a confirmation click, keeping your avatar folder and window placement.

Settings tab

• Microphone: which input device the app listens to, as a dropdown of your real capture devices.
• Mic sensitivity: boosts a quiet microphone. Its bar shows the raw signal from the mic.
• Mic activation: the level speech must pass to count as talking, set by dragging the red marker on the live meter.
• Image size: prefer the lighter _small images when your avatar pack includes them.
• Blink rate and Blink length: how often the avatar blinks and how long each blink lasts.
• Bounce and Bounce gravity: how hard the avatar hops when you start talking, and how fast the hop falls back down. Slide Bounce to the far left to turn the hop off.
• Local API: serves the local control API for stream tooling. Off by default.

Avatar tab

• Avatar folder: the folder currently loaded, with a Change button that opens a folder picker starting in Pictures/PNGTuber Studio.
• Default emotion: the emotion shown at startup. The default is always key 1.
• Hotkey map: every emotion listed with its key, both the in-window number and the global Alt+number.

OBS tab

Connects to OBS so scene switches can change your avatar's emotion. Covered in section 8.

Help and Avatar files tabs

Compact in-app versions of this page: the hotkey list for your loaded avatar, the file format reference, and where to find the shipped docs. The About block shows the app version.

5. Tuning your microphone

Two sliders, two bars, one minute:

1. Speak normally. The sensitivity bar shows your mic's raw signal. If it barely moves, drag the sensitivity handle right until the activation bar dances comfortably into its middle when you talk.
2. Set the activation marker just below where your speech lands, and above where your room noise sits. The bar turns blue while the app counts you as talking.

Detection has a short hold so the mouth does not flicker between words. If the mouth hangs open too long or clips your words, nudge the activation marker.

6. Hotkeys

On Windows the global hotkeys work as soon as the app runs. On Linux the first launch shows a system dialog asking you to approve the shortcuts; approve it once and they persist (they can be rebound later in GNOME Settings under Apps).

7. Capturing in OBS

Linux: add a Window Capture (Xcomposite) source and pick the PNGTuber Studio window. The background is transparent. Hold Alt and drag the capture's edges in the OBS preview to crop out the title bar and the bottom strip.

Windows: use Game Capture, set Mode to "Capture specific window", pick PNGTuber Studio, and check Allow Transparency.

8. Switching emotions with OBS scenes

1. In OBS: Tools, then WebSocket Server Settings. Enable the server and copy the password.
2. In the app: open Settings, OBS tab. Turn the OBS link on, check the address (localhost:4455 is standard), click the password row and type the password; it saves on its own.
3. When Status reads connected, every OBS scene appears with an emotion dropdown. Pick an emotion per scene; "no change" leaves the avatar alone when that scene becomes active. Several scenes can map to the same emotion.

9. The local API

With Local API enabled in settings, the app serves an HTTP and WebSocket API on your own machine (port 7884 by default) that stream tooling can use: switch emotions with an optional auto-revert duration, trigger a bounce, read status, and subscribe to live events like talking started. Stream Deck plugins, Streamer.bot, and plain scripts all work:

curl -X POST "http://127.0.0.1:7884/emotion/angry?duration=10s"

The complete reference ships with the app as docs/API.md.

10. Troubleshooting

• Avatar not loading: read the amber status line at the bottom of the settings panel. It names the first file that did not match the naming pattern and says why.
• Mouth never opens: check the Microphone dropdown is the right device, then follow the mic tuning steps.
• Global hotkeys silent on Linux: relaunch and approve the system dialog, or assign the keys in GNOME Settings under Apps, PNGTuber Studio.
• OBS shows a black box: on Windows use Game Capture with Allow Transparency instead of Window Capture.
• OBS tab stays disconnected: confirm the WebSocket server is enabled in OBS and the password matches; the Status line reports the exact error.