Developed by Hate and LaMDA. Puppet Desk is free PNGTuber and 2D VTuber software for Windows. Turn your own character images into a voice-reactive streaming avatar, with microphone-driven talking, automatic blinking, layered hands and props, and OBS scene switching.
Use Puppet Desk for PNGTubing, virtual puppets, livestreams, and recorded videos with OBS Studio. Save six characters with three puppet profiles each, switch views with hotkeys, and position, resize, rotate, or mirror your hand layers. Your microphone drives the mouth states; no webcam or face tracking is required.
Download Puppet Desk for Windows · Release notes
Download PuppetDesk-Windows.zip from Releases, extract it, and run Install or Update Puppet Desk.cmd. Use the desktop Puppet Desk shortcut afterwards. Future updates use Update Puppet Desk. No GitHub login, GitHub CLI, Python or compiler is needed.
Windows 11 with .NET Framework 4.8 or later is recommended. The executable is unsigned. Updates preserve local settings and retain a previous version for rollback.
Find sections by the names printed on the controls. Use Ctrl+F for a control name.
CONTENTS
- Puppet Desk overview
- Install or Update Puppet Desk
- First-time setup
- PuppetDesk Controls and PuppetDesk Puppet
- Character 1-6 / Puppet 1-3 / Rename
- Align all puppets
- Puppet views / View pictures / Fade between views
- Select Puppet / Puppet size (arms scale with it)
- Hands — Load, Select, Hand off / Hand on, Clear, Size, Rotate, Mirror, Play / Pause, Reset hand pose
- Hand joints — Pin Left hand / Pin Right hand / Lock joint
- Microphone — Start Mic / Stop Mic / Voice threshold / Mouth hold (ms) / Blink automatically for selected view / All puppets
- Key bindings — Left / Front / Right / Global (also active in other applications)
- Undo (Ctrl+Z) / Redo (Ctrl+Y)
- Saved settings, artwork and backups
- Sharing Puppet Desk
- OBS Window Capture setup
- Copy view report / Troubleshooting
- Control reference and current limits
- OBS settings — Connection, character scenes and puppet scene overrides
- Update Puppet Desk / Rollback Puppet Desk
- Minimize puppet / Restore puppet
- Donate
- Open Hands window / Hand keyframes — create, select, move, copy, paste, save and play
Puppet Desk displays a character assembled from your pictures. Microphone activity switches between idle and talking pictures. Optional automatic blinking selects blink pictures. Buttons or assigned keys turn the character Front, Left or Right.
Each puppet can have two independently positioned hand/arm layers. These layers accept still pictures or movie clips. You can resize, rotate, mirror, hide, and pin them. Once arranged, the hands follow the puppet when you move or resize its body.
Six named character buttons each hold three named puppet setups: 18 total. For example, Hate can have three outfits/poses, and Beavis has three separate setups. Only the selected character and puppet setup is displayed.
Extract the complete download ZIP and double-click Install or Update Puppet Desk.cmd. The installer downloads and verifies the published app, creates desktop shortcuts, and keeps a rollback copy when updating. No compilation is needed. Launch from the Puppet Desk desktop shortcut. Close the app before updating. Settings are stored separately in AppData and are preserved by updates.
- Select Character 1, then Puppet 1. Right-click either button to rename it.
- Expand View pictures and load your Front and Right pictures.
- Select Front and set the Puppet size slider.
- Click Select Puppet, then left-drag the puppet in the preview to place it.
- Expand Microphone, click Start Mic, and tune Voice threshold and Mouth hold.
- Load hand pictures or movies in Hands, if wanted.
- Select each hand, position it, and adjust its size and rotation.
- Set and lock joints if you want a particular rotation pivot.
- Set up Puppets 2 and 3 in the same way.
- Close normally with X or Exit Puppet Desk to save the current setup.
An empty Front setup displays a simple built-in demo face. Loading your own Front picture replaces that demo. Hands are optional.
The controls window contains the buttons, image pickers and sliders. The separate preview displays the puppet and hands on the desktop.
The top area stays above the scrolling controls: Undo | Redo | Align all puppets Character 1 | Character 2 | Character 3 | Character 4 | Character 5 | Character 6 Puppet 1 | Puppet 2 | Puppet 3 for the selected character.
Right-click any character or puppet button and choose Rename. Enter a name and press Enter/Save, or Escape/Cancel. Hover to see a long name in full.
Below that, the sections appear in this order: Puppet views Hands (Open Hands window) Microphone View pictures Key bindings Copy view report / Exit Puppet Desk / developer credit
Hand joints is inside the Hands window. Microphone, View pictures and Key bindings can collapse by clicking their headings. Click again to expand. Collapsing a section hides its controls; it does not disable its features. Collapse state is not currently saved between launches.
Resize the controls window by dragging an edge, maximise it, or scroll to reach lower sections. The preview follows normal window stacking, so an active application such as OBS can cover it.
Sliders ignore the mouse wheel. Click or drag a slider deliberately to change its value. The wheel no longer resizes hands over the preview either.
Click one of the six character buttons beneath Undo/Redo, then choose one of its three puppet buttons. Active buttons are green. Character 1 always opens on launch; each character remembers which of its three setups you last selected. Right-click a character or puppet button, choose Rename, and type up to 30 characters. Enter saves; Escape cancels. There are no permanent name fields. Each character has separate pose names, artwork, settings and histories.
Each slot keeps its own:
- Front and Right artwork selections.
- Both hand/arm files, whether pictures or movies.
- Puppet size, position and selected view.
- Hand sizes, positions, rotations, mirrors and visibility.
- Joint positions and locks.
- Voice threshold, mouth hold and per-view blink settings.
- Fade preference, view key assignments and Global preference.
Switching saves the outgoing setup and restores the incoming one. Their microphone/playback states can also change when switching during a session. After reopening the app, microphone and movies start stopped; use Start Mic and Play as needed.
Names and setups are saved between launches. Existing three-puppet data is imported into Character 1 automatically. The older files are retained. The other five characters start with empty setups. Character 1 opens by default.
Each puppet has its own Undo/Redo history for the current session. Editing the Pirate does not undo the Demon's edits when you return to the Demon.
This button is immediately to the right of Redo. The SELECTED puppet is the reference. Within the SELECTED CHARACTER, clicking it gives the other two slots the same puppet width and screen position as that reference.
Example: Set Demon to a width of 400 and position him where you want him. Keep Demon selected and click Align all puppets. Pirate and Judge receive that width and position. Switching between them now uses the same placement without manually repositioning each character.
Attached hands move and scale proportionally with their own puppet. Their relative placement, rotation, joint positions and locks are retained. The button does not copy the Demon's pictures or hands onto the other puppets.
Alignment matches the image drawing origin and width. Different source-image aspect ratios can produce different heights, and different empty margins in your artwork can make the visible characters appear slightly offset. It does not detect faces or automatically crop artwork to equal visible body sizes.
Changes are saved. To undo alignment for a particular affected puppet, switch to that puppet and click Undo. Each affected slot has its own alignment edit; the reference puppet is unchanged.
The view buttons are ordered Left, Front, Right. Front is in the middle. Left is a horizontal reflection of the Right artwork. There are no separate Left image slots in this version.
In View pictures, load these four states for Front and again for Right: Idle: Mouth closed, eyes open. Talking: Mouth open, eyes open. Blink: Mouth closed, eyes closed. Talk blink: Mouth open, eyes closed.
The picker accepts PNG, JPG/JPEG, GIF and BMP. Puppet GIFs are treated as pictures, not as an animated character system. Use matching canvas sizes and character placement across states for stable visual changes. Repeated file names in different folders are permitted; the program uses full file paths.
Click a picture button to choose or replace its file. Click the adjacent X button to clear that slot. Clearing a slot does not delete its file from disk. Hover over the displayed filename to see the full path.
When a state is missing, the program tries another available picture from the same view. Left uses Right's available pictures, mirrored. Load at least one Right picture before selecting Left or Right. A side view does not deliberately borrow a Front picture as its missing-state fallback.
Fade between views is optional. Enabled: the newly selected view briefly fades up to full opacity over about 300 milliseconds. Disabled: the switch is immediate. It is not an animation that turns or morphs the body.
The status beside Fade identifies the active view and drawing slot. Hover there to inspect the selected image path.
Select Puppet chooses the body for dragging. Left-drag a visible part of the preview to move the selected layer. Selection comes from the controls buttons, so you can choose the body even when a hand overlaps it.
Right-drag moves the entire preview window, carrying its contents together. When dragging a layer toward the left or top edge, the preview can reposition itself to allow movement onto monitors left of or above the primary screen.
Puppet size sets the body image's drawing width, currently 150 to 1,000 pixels. Its height follows the reference artwork's aspect ratio. This slider scales both hands and their offsets from the body at the same time, including hidden hands. Arrange the arms first, then resize the whole puppet as a group.
Moving the body also carries both hands. Selecting and moving a hand adjusts that hand independently, unless its joint is locked.
9. Hands — Load, Select, Hand off / Hand on, Clear, Size, Rotate, Mirror, Play / Pause, Reset hand pose
Click Open Hands window to access the hand controls and joints. See section 23 for keyframe animation and saved presets.
Left hand and Right hand are independent overlay slots. They can also hold props such as a martini glass, gavel, or other artwork.
Load left hand / Load right hand: Choose PNG, JPG/JPEG, BMP, GIF or a movie. The movie filter includes MP4, WMV, AVI, MOV and M4V; playback depends on Windows codec support. Transparent PNGs preserve their transparency. GIFs are loaded as still hand images.
Loading turns that hand on and selects it for movement. A first-time load, very tiny hand, or hand detected outside the preview/screens is repositioned beside the puppet at a useful size. Replacing an already visible hand usually keeps its pose. A file with saved keyframes starts at its first saved key. Automatic loading of saved profiles restores the saved profile pose.
Select Left hand / Select Right hand: Choose which hand responds to left-dragging in the preview.
Hand off / Hand on: The button describes its NEXT action. Hand off means the hand is currently shown; click to hide it. Hand on means it is hidden; click to show it. This stops keyframe playback and restores the normal pose, then hides or shows the hand. It retains the file and does not pause a playing movie.
Clear: Removes the loaded hand file from the slot without deleting it from disk. It does not serve as a pose reset. Undo can restore the selection if its original file is still available.
Size: Resizes this hand independently while retaining its aspect ratio. The slider normally spans 1 to 10,000 pixels; group scaling may extend it. The chosen pivot stays in place during independent resizing.
Rotate: Turns the hand from -180 to +180 degrees around its pivot. A new/reset hand uses its centre until you choose a different joint.
Mirror: Flips the hand picture or movie horizontally. Each hand has its own switch. This is separate from the Left body view mirroring the Right body artwork.
Play / Pause: Available for movie hands once the movie opens. Play runs the clip, Pause stops at the current point, and a playing clip loops at its end. Movie audio is muted. This button is disabled for still pictures.
Reset hand pose: Places the hand beside the puppet at roughly half the puppet's width, resets rotation to zero and the pivot to its centre, unlocks the joint, turns the hand on, and selects it. The file and Mirror setting are retained. This action can be undone. Use it when a hand is lost, tiny or badly placed.
Movie transparency: The program removes vivid green pixels from movie frames. This is a fixed green-key operation, not an adjustable keying panel. Green objects within the clip can also be affected. Ordinary image backgrounds are not processed by that movie keyer. A JPG has no alpha transparency; use a transparent PNG for a clean still-image cutout.
Hands render above the body. The right-hand layer renders above the left-hand layer where they overlap. Selecting a layer does not change that drawing order.
Use a joint to make an arm rotate around an elbow, wrist or another point.
- Load and position the hand.
- Expand Hand joints.
- Unlock that hand if necessary.
- Click Pin left hand or Pin right hand.
- With the cross cursor, click the intended joint on the hand in the preview.
- Adjust Rotate to check the movement.
- Enable Lock joint when satisfied, then collapse Hand joints if desired.
Choosing a pivot preserves the hand's current visible placement. Rotation and independent resizing then use that pivot. Clicking the pin button again cancels picking; choosing a layer also cancels it.
Lock joint prevents repinning and dragging that hand independently. It still allows rotation and resizing. Moving/scaling the whole puppet carries locked hands with it. Unlock the joint when you want to reposition the arm.
This is one pivot per hand layer. It does not bend a single picture into a multi-joint skeleton, track a face, or automatically reposition arms for each Front/Left/Right view. Each puppet currently has one shared hand pose across its body views.
11. Microphone — Start Mic / Stop Mic / Voice threshold / Mouth hold (ms) / Blink automatically for selected view / All puppets
All puppets (share microphone across all characters): Check this to use the current Voice threshold and Mouth hold for all six characters and all three profiles within each character (18 setups). Adjusting either slider changes the shared tuning. Switching characters or profiles keeps the mic's current running state while sharing is enabled. Uncheck to tune each profile independently again; each starts from the last shared values. This option and shared values are saved between launches. The app still starts with the microphone stopped after reopening. Blink preferences remain specific to each view/profile.
Start Mic starts capture from the Windows default recording microphone. Stop Mic stops it. Choose the desired default device in Windows before starting capture; this version has no device selector inside Puppet Desk.
Voice threshold: Sets how loud the input must be to trigger talking. Lower values react to quieter sounds. Raise it if room noise triggers the mouth. Speak normally while watching the green live level and adjust until speech opens the mouth while background noise does not.
Mouth hold: Keeps the mouth open briefly after the last above-threshold input. Range: 0 to 500 milliseconds. Increasing it helps bridge tiny gaps between syllables; decreasing it makes closing more immediate. Zero can prevent visible talking because the hold interval has no duration; start above zero when tuning.
Both sliders display live microphone activity in green. The hold slider's value is a duration, not another loudness threshold. A separate level bar is also shown beside Start/Stop Mic. These are relative indicators, not calibrated sound-pressure or decibel meters.
Blink automatically for selected view: Enables periodic blinking for the current Front, Left or Right view. Blinks last about 140 milliseconds, with random intervals of 2.5 to 6.5 seconds. Each view remembers its own preference. Blink still works while the mic is off. If an appropriate blink picture is missing, the same-view fallback applies. While silent, a blink uses Blink; while talking, it uses Talk blink. Voice above the threshold selects Talking; after Mouth hold expires it returns to Idle. This swaps your supplied pictures; it does not animate eyes or mouths inside one picture.
After launching the app, click Start Mic. Changing puppet slots restores that slot's tuning and can change whether the microphone is running in that session.
Default view keys: F6 = Left F7 = Front F8 = Right
To change one, click its field and press your preferred key. Ordinary letters and numbers are allowed; modifiers are optional. You can also use combinations such as Ctrl+Alt+1. Click elsewhere when finished. Backspace or Delete clears the assignment. Duplicate view assignments are rejected.
Global unchecked: View keys act only while Puppet Desk Controls is the active window. Merely leaving the controls open behind Firefox is not enough. They do not operate the puppet while another application, or the separate preview, is active.
Global checked: View keys can operate while Firefox, OBS or another application is active. A globally reserved plain letter also acts as a puppet key when you type in another application. Choose keys with that behaviour in mind.
Bindings are temporarily released while you edit key fields or puppet names. If Windows cannot reserve a binding, its field can show "in use". Choose a free key or combination. Ctrl+Z, Ctrl+Y and Ctrl+Shift+Z are reserved for history. These view bindings and Global preference are stored per puppet slot. Global view hotkeys and shared microphone settings are separate options.
For a mouse with programmable buttons, assign the matching keyboard keystroke in your mouse's software. Puppet Desk receives that keystroke as a view command. There are currently no separate bindings for switching characters, puppet slots or hands.
Undo and Redo stay at the top of the controls. Ctrl+Z Undo Ctrl+Y Redo Ctrl+Shift+Z Redo
These editing shortcuts work with the controls or preview active. They are not system-wide Undo commands. When editing a name text field, normal text editing takes priority; key-binding fields capture input for assignment.
History covers completed setup changes such as moving the puppet/window, scaling, rotating, moving or pinning hands, changing visibility or mirrors, selecting/clearing artwork, and changing tuning/settings or playback state. A continuous mouse drag is normally one completed edit.
Each puppet keeps up to 100 previous edits for the current session. A new edit after Undo clears that puppet's Redo history. History is not retained when the app closes. Names, section expansion and selecting which layer to work with are not puppet-pose history items. Undo does not seek a movie back to an earlier timestamp or recover files deleted from the hard drive.
After Align all puppets, switch to each affected puppet to undo its alignment.
Puppet Desk stores settings separately from the EXE in: %APPDATA%\PuppetDesk
To open the folder:
- Press Windows key + R.
- Paste %APPDATA%\PuppetDesk
- Press Enter.
Files there include: characters.txt Character/profile names, selected poses, and shared mic options. character-1 through character-6: folders, each containing puppet-1.txt, puppet-2.txt and puppet-3.txt for that character. Root puppet-1.txt / puppet-2.txt / puppet-3.txt and puppets.txt may remain from the earlier version; those are migration sources. settings.txt Possible older single-puppet file retained from earlier builds.
Several actions save immediately, including loading/clearing files, changing slots, alignment and leaving name fields. Close normally with X or Exit Puppet Desk to save the latest adjustments. A forced process termination can lose changes made since the last save.
Artwork and movies remain in their original folders. Settings contain paths to them, not copies of their contents. Renaming or moving a selected file can prevent it loading next time; use its picker to select the new location.
To back up a setup, close the app, copy the settings folder, and separately back up the artwork/movie files. Restoring to another PC may require reselecting files because the original folder paths differ.
Different downloaded EXEs reuse this same settings folder. Deleting old build folders does not create or remove separate installed versions. Do not delete the settings folder unless you intend to remove your saved configurations. Avoid running multiple copies at once because they write to the same files.
Share Puppet Desk using its official GitHub page: https://github.com/anonimations696/Puppet-Desk
Only trust Puppet Desk downloads and updates from this original repository and its Releases page. Do not trust download links, mirrors or copies hosted elsewhere, even if they use the Puppet Desk name or logo. Share the official link above.
Choose the separate PuppetDesk Puppet preview as the window source for your scene, rather than the controls window. If the capture displays a green background, apply a green Chroma Key filter to that source in OBS. Exact capture results depend on OBS capture settings and the Windows environment.
Puppet Desk does not provide its own virtual camera, recording timeline or finished-video export. OBS handles your scene composition, recording or virtual-camera output. Puppet Desk supplies the animated visual.
Microphone activity drives the mouth. Computer or browser audio is not intentionally used as the input; routing it into your recording microphone through another program can make it trigger talking.
Hand is missing:
- If the button says Hand on, click it to show that hand.
- Check the slot has a filename.
- Select that hand and use Reset hand pose.
- Reload its file; loading turns it on and selects it.
- Check whether an opaque right-hand picture is covering the left hand.
- A still image's Play button being disabled is normal.
- If the problem persists, provide the exact image and a diagnostic report.
Hand will not move independently:
- Select the correct layer.
- Unlock its joint. A locked joint deliberately prevents hand dragging.
- Finish or cancel pin-picking mode before attempting a normal drag.
Hand shows a solid background:
- Verify that the source is a transparent PNG if you need a cutout.
- A JPG's background is part of the picture.
- Movie green keying applies to movie frames, not arbitrary still backgrounds.
Body changes appear to jump or flip:
- Confirm each loaded state actually faces the intended direction.
- Left is always a mirror of Right in this version.
- Check alignment and empty margins within the different source images.
- Copy the view report to identify which path is being drawn.
Mouth does not respond:
- Start Mic and check the live level.
- Confirm Windows' default recording microphone.
- Lower Voice threshold and set Mouth hold above zero.
- Verify a talking picture is loaded and visibly differs from idle.
Movie will not play:
- Allow it time to open before using Play.
- Read any decoder error shown by the app.
- File extension alone does not guarantee Windows can decode the codec.
Hotkey does not respond:
- With Global off, activate the controls window.
- Click away from a key field or name field after editing.
- Check for "in use" and try a different binding.
- Remember that each puppet has its own assignments.
Build fails:
- Close the existing Puppet Desk.exe before rebuilding it.
- Extract the ZIP fully and keep the source/icon beside the batch file.
- Copy the full compiler error text if further help is needed.
Old blue-border icon still appears:
- Check you rebuilt and opened the current EXE.
- Windows may retain an old small icon for an existing path/shortcut.
- Recreate an old shortcut or taskbar pin for the current EXE if needed.
Copy view report: This button copies diagnostic text to the clipboard. It includes the active view, drawing slots, loaded artwork paths, blink/fade state, hand paths, visibility, dimensions, positions, rotation and pivots, plus recent frame changes. Paste it when requesting troubleshooting. It includes full local paths, so inspect it before posting publicly. It does not upload itself.
Current limits:
- Six characters, each with three setups; one displayed puppet at a time.
- Two hand/prop layers per puppet.
- Front artwork plus Right artwork; Left mirrors Right.
- One hand pose per puppet, shared across its directional views.
- One pivot per hand; no automatic skeletal bending or face tracking.
- GIFs are still pictures in this workflow.
- Video support depends on Windows codecs.
- No built-in project packaging, video editor, virtual camera or export.
- Windows behaviour must be checked on the recipient's actual PC; source syntax checks alone do not verify capture, drivers or movie decoding.
Quick reference: Left drag Move the selected puppet/hand layer. Right drag Move the whole preview window. Puppet size Scale the puppet and both attached hands together. Hand Size Scale that hand independently around its pivot. Hand Rotate Rotate that hand around its pivot. Hand off/on Hide/show without clearing its file. Clear Remove a slot's file selection, not the disk file. Reset hand pose Recover a hand beside the puppet; reset pivot/rotation. Pin hand Choose a rotation joint by clicking the preview. Lock joint Prevent independent dragging and repinning. Align all puppets Match other slots to the active body's width/location. Ctrl+Z Undo in the current puppet's session history. Ctrl+Y Redo (Ctrl+Shift+Z also works). F6 / F7 / F8 Default Left / Front / Right view keys. X / Exit Close and save.
Developed by Hate and LaMDA.
Right-click any of the six character buttons, or one of the three puppet profile buttons, and choose OBS settings. Rename remains in the same menu. Opening this menu or dialog does not select that character or change the live OBS scene.
Requires .NET Framework 4.5 or newer (Windows 11 includes a newer version).
First-time connection (OBS 28 or newer, WebSocket v5):
- In OBS, open Tools > WebSocket Server Settings and enable the server.
- In Puppet Desk, right-click a character > OBS settings.
- Leave Host at 127.0.0.1 when OBS runs on this same PC. Enter the port and password shown in OBS (the usual port is 4455).
- Click Test connection / refresh scenes. This fetches scenes from the current OBS scene collection and reports connection errors in the dialog.
- Tick Enable automatic OBS scene switching. This is one global switch.
- Choose Use the scene selected below, then select a scene from the list. You can also type its exact name, including spaces and capitalisation.
- Save, then click that character button to apply its scene.
Character scenes: Assign Vader to your Vader scene and Hate to your office scene, for example. Each character's three puppet profiles inherit that character's assignment by default. Front/Left/Right view changes do not change OBS scenes. Do not change the OBS scene leaves OBS on whatever scene it already has.
Optional profile overrides: Right-click a Puppet 1/2/3 button within the selected character. Use this character's scene: inherit the parent character's assignment. Use the scene selected below: this profile uses its own assigned scene. Do not change the OBS scene: this profile leaves OBS untouched, even when its parent character has an assigned scene. A character remembers its last puppet profile, so that profile's override also applies when you return to the character.
Operation:
- Click a character or puppet profile to load it and request its scene.
- Clicking the already-selected button retries the scene request. This is useful after starting OBS later or after restoring a lost connection.
- Saving settings or starting Puppet Desk does not switch live output by itself. Click a character/profile when you are ready.
- The request changes OBS's PROGRAM (live/output) scene, including when Studio Mode is on. It is not limited to Studio Mode's preview pane.
- Requests run asynchronously with a five-second timeout; missing OBS, a wrong password, or a missing scene does not freeze puppet controls.
- Rapid button changes cancel older pending requests in favour of the newest choice. A request already received by OBS may briefly take effect.
- Reopen OBS settings to see the last switch result or test the connection.
- This uses short connections for each operation. Connected successfully describes the completed test; it is not a permanent online indicator.
- OBS settings are saved separately and are not part of Undo/Redo.
- Changes to host, port, password, or the enable checkbox affect all characters. Scene choices belong to the button you right-clicked.
- If you rename a scene in OBS or switch scene collections, refresh the list and update the saved scene assignment in Puppet Desk.
Set up your backdrop scenes in OBS first and include the PuppetDesk Puppet capture in each appropriate scene. Puppet Desk changes scenes; it does not create backdrops, sources, or scene collections. No Python or additional OBS plugin is required for this connection on OBS 28 and newer.
OBS settings live in %APPDATA%\PuppetDesk\obs.txt. The password is protected for your Windows user account rather than embedded in the EXE. Moving this settings file to another Windows account can require re-entering the password. The distributed ZIP contains no personal OBS settings or passwords.
Close Puppet Desk, then use the Update Puppet Desk desktop shortcut. The first installation uses Install or Update Puppet Desk.cmd and its PS1 companion. The public updater downloads the latest published stable Puppet Desk release. No GitHub account or GitHub CLI is needed. Your settings remain in AppData.
Use Minimize puppet under Puppet views to temporarily get the puppet off your desktop. The same button changes to Restore puppet and brings it back. OBS Window Capture may freeze or go blank while the puppet is minimized; this is expected. Restore resumes normal drawing with the current character, profile, view, hands and size. Existing dragging/resizing behaviour is retained. The app keeps normal window coordinates separately from Windows' minimized coordinates, so minimize/restore does not change saved placement or alignments. Character/profile changes while minimized load normally and appear on restore.
RETURNING FROM THE EXPERIMENTAL BROWSER OUTPUT The separate Browser output and Hide desktop puppet option have been removed. In OBS, disable/remove Puppet Desk's Browser Source and re-enable your original Window Capture source. If needed, select the PuppetDesk Puppet window again. All your saved characters and OBS scene-switching assignments are preserved. The old browser-output.txt settings file is ignored and can be left alone. The app no longer runs the local Browser output server.
Click Donate at the top of Puppet Desk Controls to open the support dialog. It links to @DemonSir696 on X and explains how to support future Puppet Desk projects, including Puppet Desk Audio Bridge.
The X Money instructions apply when that feature is available to your X account. Review the recipient and payment details in X before sending. Puppet Desk does not collect payment details or process donations. Click Close to return to the controls.
Click Open Hands window in the main controls. This opens a separate, resizable editor containing both hand slots, Hand joints and Hand keyframes. Click either the main controls or Hands to bring that window forward. Closing Hands with X hides the editor; it does not exit Puppet Desk or stop a playing animation. Use Open Hands window to reopen it.
Hands is a tool window excluded from OBS automatic Window Capture matching. Continue capturing PuppetDesk Puppet, not the controls. Global Left / Front / Right hotkeys remain active while Hands is active when Global is checked.
Choose the hand to animate using the dropdown in Hand keyframes or the Select Left hand / Select Right hand buttons. Each slot plays independently. The slots are layers, not automatic left/right versions of the same image. Load a still picture or movie using the matching Load hand button.
- Load your facepalm hand and select it.
- Set Time (seconds) to 0.00. Position, size and rotate the hand where the gesture should begin. Unlock its joint if you need to drag it.
- Click Add / replace key. A blue circle appears at that time.
- Set Time (seconds) to 1.00. Move the hand to the forehead and adjust its rotation and size, then click Add / replace key again.
- To hold the facepalm, copy that key and paste it at a later time. To return to the starting pose, copy the first key and paste it after the hold.
- Enter an Animation name, click Save, then Play animation.
Captures the currently posed hand at the time shown. A key stores position, size, rotation, pivot, mirror and visibility. Adding at an existing key's exact time replaces that key. Add at least two keys at different times to play an animation. Position, size and rotation interpolate between keys; mirror and visibility change at their key times. Gestures follow the puppet's position and scale when you move or resize its body.
Click a blue circle to select and preview that key. Its outline highlights the selection. Drag it left or right to change its time without changing its saved pose. Release to save the new timing. Keys stop before neighbouring keys so dragging cannot accidentally overwrite another pose. The list below the timeline also lets you select a key and preview its pose. To change a pose, preview the key, adjust the hand, and use Add / replace key at the same time. Previewing alone does not replace a saved key.
With a blue dot selected, the left/right arrow buttons move that KEY by 0.10 seconds per click and save the timing. It stays selected while using the arrows. Click elsewhere to clear the dot selection. With no dot selected, the arrows rewind/advance the preview time by 0.10 seconds. Click or drag empty timeline space to scrub the animation. The orange line shows the current time; the seconds field stays in sync. Typing a time or using the seconds field's up/down buttons chooses the time for a new key without changing the hand's pose. Click Preview time to apply the animation at that time. The timeline expands for longer gestures, with a maximum duration of 120 seconds. Mouse-wheel scrolling does not move it.
Right-click a blue dot and choose Copy keyframe. Right-click the timeline where you want the duplicate and choose Paste keyframe. The new dot keeps the copied pose at the clicked time and saves automatically. Copying keeps a snapshot: editing the original afterwards does not change the copy. Paste repeatedly to repeat a pose or create a hold. At an occupied time, the menu explicitly says Paste keyframe (replace here). Paste is disabled until you copy a key. The copy lasts until the app closes.
Give the gesture a recognisable name, such as Facepalm or Martini, and click Save. Adding, deleting, pasting and retiming keys also save automatically. Click Save after changing the name or Loop preference. Saved hands lists the saved hand animations. Choose one and click Load saved to load its artwork and keys into the selected Left or Right hand slot. Loading an animation immediately positions that hand at its first saved pose. It does not start playback automatically.
Example: save Facepalm, load a martini hand and save its own keys, then choose Facepalm in Saved hands and Load saved. Play animation runs Facepalm's saved gesture again. You can also reload the original file with Load hand.
There is ONE saved animation per hand file's full path. Different files keep separate animations, including files with the same name in different folders. Loading the same file uses the same saved preset across slots and characters; saving replaces that file's preset. Keep artwork in its original location: renaming or moving it changes the association. Changing Animation name labels the preset; it does not create another preset for the same file.
Play animation runs the keyframes for the selected hand. It works for still PNGs as well as movie layers. Pause holds the current animation position. Play animation resumes, or restarts when already at the end. At the end, a non-looping animation holds its final pose. Loop repeats the sequence. Stop / restore stops and restores the hand's pose from before preview or playback. Switching character or puppet profile stops its hand animations. Movie Play / Pause controls the video clip separately from Play animation.
These buttons describe the NEXT action. Clicking either stops that hand's keyframe playback, restores its normal pose and hides/shows it as requested. A visible hand remains visible when you select the other hand or puppet. Movie playback is separate. Loading a hand turns it on; Clear removes it from the slot without deleting the artwork or its saved animation.
Select a key, then Delete key to remove it and save the change. Clear keys asks before removing all keys from this hand's preset. It does not delete the hand artwork. Keyframe edits are not included in puppet Undo/Redo.
Presets are stored in %APPDATA%\PuppetDesk\hand-animations as JSON files. Updates preserve them along with your other local settings. Back up this folder and the original artwork if you want to keep copies. The preset records the artwork path, not a copy of the picture or movie. There is no portable animation export/import button. Public and development settings remain separate; development presets are not automatically copied to public.