Peraravatar+

Getting started

Allow mic → choose how to build → choose how lip sync works → upload images → register vowels (if lip sync uses vowels) → adjust the motion → export as HTML → add to OBS

Mic

• Allow mic: starts using the mic. Pick the mic to use in the dropdown next to it (default: Default mic)
• The exported HTML looks for the mic chosen here by name (if not found, it uses the Windows default mic)
• Volume: the current volume. The marks are the thresholds
• Auto calibrate: measures silence and your speaking voice and sets the thresholds automatically
• Volume test: moves the volume by hand without the mic to check the lip sync (only with “By volume”)
• Register vowels: say a, i, u, e, o one at a time so it learns the vowels of your voice (register it if lip sync uses vowels)
• On the right, the mouth shown at the current volume (such as Mouth: closed) and the current vowel (such as Vowel: A) appear

Auto calibrate

1. Measuring room noise: stay quiet and wait
2. Measuring your voice: while the bar fills, keep talking in your usual streaming voice
3. Results: the blue marks on the meter are the new values. If they look right, press “Apply”

It changes the lip sync stages, the loud reaction and each expression’s trigger volume together. Once done, the button becomes “Recalibrate”.

Register vowels

Say “ah”, “ee”, “oo”, “eh”, “oh” one at a time and hold each. “Registration results” shows how often your voice was recognized correctly; if it looks right, press “Apply”. Once done, the button becomes “Re-register vowels”.

Choose how to build

What differs is how blinking, lip sync and expressions are made.

With “Build from one image”, custom expressions can also be made by combining eye and mouth parts (a single image per expression works too). Decorations are available only with “Build from one image”.

How lip sync works

“Lip sync” on the “Images” tab has these values with either method.

With “By volume”, the value of stage 1 also serves as the “Silence threshold”. Below it, the mouth closes.

Prepare each image

Images to prepare

Recommended image specs:

• Size: 600 × 900 to 1080 × 1620px (portrait, 2:3)
• Format: PNG or WebP with a transparent background (JPEG and BMP can’t be transparent)
• PNG / JPEG / BMP are optimized automatically when imported
• “Position & size” adjusts the position and size of each image

Drop images all at once

If a file name contains one of these words (separated by underscores or hyphens), it goes into that slot automatically (not case-sensitive; if several match, rows higher in the table take priority).

Buttons for each image

Stop motion to check: press one of the buttons in the row (Normal, Blink (eyes closed), mouths, etc.) to stop the motion and show only that image. Press the selected button again, or “Exit preview” above the avatar, to release it.

Lip sync

• By vowel: the five mouths “A” to “O”
• By volume: Mouth stage 1 and up. Each stage’s value (Volume ≥) is the lowest volume that shows that mouth (kept in ascending order). Put several images in one stage and one of them is picked. Add more with ”+ Add stage”

Build from one image

Base image

Eye and mouth parts are layered on this one image to create blinking and lip sync. It doesn’t work with a full-body image where the face is small (as a guide, the eyes should be at least 40px wide).

Drop base, look-away and expression images all at once

Layered parts (eyes, brows, mouth) can’t be added here. Put them in “Layered parts” below. A name with left / right / 左 / 右 becomes a look-away image (e.g. normal_left is Look away (left)).

Images named like mouth or close aren’t used with this method; they are kept as images for “Prepare each image”. Switch the method to “Prepare each image” and they are used as they are.

Base image type

Eye and mouth positions

Check “Move brows separately” and the heading becomes “Eye, brow and mouth positions”, with Left brow and Right brow added.

1. Press “Set” and a frame appears over the avatar
2. Drag from edge to edge where you want the part. The part is placed at the center of the frame and sized to its width
3. While the frame is shown, the round handles adjust the size, tilt and height (Esc cancels the pick). Use the wheel to zoom and drag an empty area to pan the view
4. When you’re done, press “Done” above the avatar or on that part’s button to close the editor

• “Left eye” and “Right eye” mean left and right as you see the screen, not from the character’s point of view
• “Fit”, “Face”, ”−” and ”+” above the editor change the zoom (“Face” zooms to the face)

Move brows separately

• Layer brow images on a blank-face base to move them separately from the eyes in expressions and blinks
• Leave it unchecked if your eye images include the brows, or if brows are drawn on the base

Left eye, Right eye, Mouth (plus Left brow and Right brow when moving brows separately)

• “Position & size” lets you fix X (px) / Y (px) / Width (px) / Height (px) / Tilt (°) as numbers
• “Delete” removes that position
• Make symmetric: makes the left and right eyes (and brows when moving them separately) symmetric. Size and height become the average of both sides, tilt is mirrored, and the left-right positions stay
• Delete all positions: removes all positions (part images and look-away settings stay)

Skin color for hiding the eyes and mouth

Shown when the base image type is “Eyes and mouth drawn in (*not recommended)”.

• The original eyes and mouth are filled with this color, then the part images are layered on top
• Choose skin that isn’t covered by hair or brows (press “Set” for “Skin color” and click on the image)
• Outside the frame, only areas close to this color are painted (brows and hair aren’t erased)
• Edge feather (px) blurs the painted edge

Layered parts

Images for layered parts

• Format: transparent PNG / WebP
• Size: a square from 150 × 150 to 300 × 300px, with the part roughly centered
• Scaled to the width of the frame you set. Stretching makes them rough
• Placed automatically to fit the frame. Left-right, up-down and size can be adjusted per image with “Position & size”
• For eyes and brows, a screen asks whether the image is the left or right one when you add it. Unless the eyes are asymmetric (odd eyes, one eye closed, etc.), one eye is enough

“Download parts template (psd)” under the “Images for layered parts” notes downloads a PSD file (a 300 × 300 square) for drawing layered part images.

Buttons for each part

Stop motion to check: press one of the buttons in the row (Normal, Closed eyes, Closed mouth, mouths, etc.) to stop the motion and show only that image. Press the selected button again, or “Exit preview” above the avatar, to release it.

Delete all layered parts: removes all layered part images (eye and mouth positions stay).

Lip sync

Look away

Set it up if you need it. Check “Look away (left)” and “Look away (right)” to use them. “Preview” is at the top right of the card.

“Method” chooses between combining parts and using a single image.

Decorations

Available with “Build from one image”.

• Layer images such as glasses, cat ears or hair clips anywhere you like (up to 8. Format: transparent PNG / WebP)
• An image the same size as the base image is placed exactly where it was drawn
• Prepare the “Swap image” at the same size as that decoration’s image
• Items lower in the list are drawn in front (“Up” / “Down” to reorder)

Placement

Add one with ”+ Add decoration” or press “Place” to move it directly on the avatar.

When you’re done, press “Done” above the avatar or on that part’s button to close the editor.

Card items

Motion

The options that depend on “a chosen custom expression” can’t be selected unless there is a custom expression with an image or parts.

“Delete all decorations” removes them all.

Custom expressions

Assign any expression you like, such as smiling, crying or angry. Add one with ”+ Add expression”.

• Press the key button, then press the key you want (Backspace for no key, Esc to cancel). H (show / hide the menu) and Y (look away) can’t be assigned
• Keys assigned here are separate from OBS hotkeys

By default, Surprised (Z, Recoil (pull back)) / Happy (X, Bounce (light hops)) / Crying (C, Shake (small tremble)) are included.

Card items

“Preview” and “Delete” are at the top right of the card. Fine-tune each action under “Expression switching and actions” on the Motion tab.

Method

With “Build from one image”, “Method” chooses between combining parts and using a single image. With “Prepare each image”, it’s a single image only.

Motion tab

Motion for the whole avatar. Decoration motion is set on each part in the “Images” tab.

• Squish: the avatar squashes, stretches and bounces like mochi when you talk
• Loud reaction: when you shout, the avatar briefly zooms in. Its trigger volume is also used by Squish and the decoration motion that sways with your voice
• Look away: while you’re quiet, the avatar looks away now and then. Press the Y key to look away at any time
• Sleepy mode: if silence continues, blinks get longer until the eyes stay closed
• Expression switching and actions: switching to an expression or look away fades briefly from the previous image (0 switches instantly)

Export tab

Export HTML

• Export avatar as HTML: exports the current state as a single HTML (peraravatar-plus-avatar.html). Settings can’t be adjusted inside the exported HTML. For adding it to OBS, see Adding to OBS
• Keep the background in the export: the exported HTML has a transparent background. Check this to export with the background chosen in “Display” in the header (for example, to export a solid color and key it out in OBS)
• If there is something to check before exporting (vowels not registered, sample images in use, expressions with no key, etc.), a confirmation appears. To ignore it, export with “Export anyway”

Switch expressions while streaming

Export OBS hotkey script: saves a script (peraravatar-plus-hotkeys.lua) that switches expressions with OBS hotkeys. For how to use it, see Switch expressions while streaming

Transfer & backup

Save your settings to a file to move them to another device or in case your browser data is lost.

• Export JSON file: saves peraravatar-plus-config.json. It includes everything, even what isn’t shown on screen, such as the images and settings of the method you aren’t using
• Load JSON / HTML file: loads a saved JSON or an exported avatar HTML. Your current settings and images are replaced with the file’s contents. Loading from HTML restores only the images and settings of the method used when it was exported

URL parameters

Add these to the end of the URL of the exported HTML.

Adding to OBS

1. Export the HTML: “Export avatar as HTML” on the “Export” tab

2. OBS launch flag: to use the mic, OBS needs the launch flag --use-fake-ui-for-media-stream. Right-click the OBS shortcut (desktop, etc.) → Properties → edit “Target” like this.

   "C:\Program Files\obs-studio\bin\64bit\obs64.exe" --use-fake-ui-for-media-stream --autoplay-policy=no-user-gesture-required

   If “Start in” is empty, set it to C:\Program Files\obs-studio\bin\64bit. Without this flag, the browser source can’t get mic permission.

3. Add a “Browser” source: leave “Local file” unchecked and put the location of the exported HTML in the URL field (checking it disables the mic)

4. How to write the URL: not as C:\Users\…\peraravatar-plus-avatar.html, but with file:/// in front and \ turned into /: file:///C:/Users/…/peraravatar-plus-avatar.html

5. Size: set the OBS browser source to the same aspect ratio as the avatar to fit it with no margins (the “Export” tab shows the current image size). If decorations move beyond the base image, transparent margins are added to the sides and top to cover their range of motion

The mic chosen in the editor is looked up by name (if not found, the Windows default mic is used).

Switch expressions while streaming

An OBS browser source doesn’t receive keyboard input, so switch expressions in one of these ways.

Switch even during games

1. Save peraravatar-plus-hotkeys.lua with “Export OBS hotkey script” on the “Export” tab
2. Add it in OBS “Tools → Scripts” and an item for each expression appears in “Settings → Hotkeys”. The assigned keys work even when OBS isn’t focused
3. By default, Ctrl+Shift+1–8 are expressions, Ctrl+Shift+9 is look away and Ctrl+Shift+0 clears the expression (change them in “Settings → Hotkeys”)

After adding, removing or renaming custom expressions, peraravatar-plus-hotkeys.lua needs updating too. Export it again, overwrite the old peraravatar-plus-hotkeys.lua and reload it in “Tools → Scripts” (assigned keys are kept).

Switch with buttons

In OBS “Docks → Custom Browser Docks”, add the browser source URL with ?controller at the end to get a panel of expression buttons (Peraravatar+ Controller).

file:///C:/Users/…/peraravatar-plus-avatar.html?controller

The controller dock can be placed anywhere, just like any other dock.

• Press a button to switch to that expression; press it again to go back
• There are also “Clear expression” and “Look away (Y)” buttons
• You can also click anywhere in the dock and press the keys shown on the buttons
• If Connected to the avatar doesn’t appear at the top right, the setup isn’t working
• Opening it in a browser doesn’t reach the avatar in OBS. Use it from the OBS dock

If you close the controller dock by mistake, it is listed at the bottom of the “Docks” menu, so open it from there.

Language / view settings

Everything below is switched from the header and persisted in localStorage:

• Language: 日本語 / English — the UI text. The exported avatar HTML, the controller and the OBS script use the language at the time of export
• Theme: Dark / Light / Fancy / Handcraft — the editor colors only (the avatar is unaffected)
• Display: under “Menu”, Text size (90% / 100% / 110% / 125% / 150%) / Menu position (Right / Left); under “Background (for checking transparency)”, Background type (Transparent (for OBS) / Checkerboard / Solid color) / Background color

Data storage

• Settings and images are saved in the browser automatically
• ↶ Undo / ↷ Redo: Ctrl+Z / Ctrl+Y
• Reset (initialize): returns all settings (including images) to the defaults of the current method. Registered vowels and the mic choice are kept
• For backups, see Transfer & backup

Shortcuts

For shortcuts while placing decorations, see Decorations.

Credit

Crediting the tool in your streams or personal projects is not required, but it is always encouraging.

Standard format

Peraravatar+ by Ichigyun
https://gyungyun.com/en/works/peraravatar-plus

Short format

Avatar: Peraravatar+ (gyungyun.com) / @zkmy_kuro

See the credit policy on the top page for the general guide.