Pyngtube

A simplistic Python application for two-state animation PNGtubing, using only flatfiles and images for configuration.

Why Another VTuber App?

Several applications exist in this space, but most of them are either non-free or complicated and use strange marshalled data formats while providing excessive, confusing features that are not necessary for a simple approach. Pyngtube aims to provide a simple set of features in an accessible format using only flat images and YAML files in a way that can be understood and put into use in minutes.

Pyngtube targets a simple "two-state animation" approach. It doesn't do any kind of facial detection and instead monitors microphone amplitude. The application displays a "closed mouth" image when the microphone is quiet and an "open mouth" image when it's not. That's all there is to it.

A couple of other fun features exist such as minor movement animations when the user is talking and randomized blinking, but these are wholly optional and default to off if not configured at all. They can be ignored if all you want is the core experience.

Requirements and Installation

pyngtube is built for Python3. Python2 is long since EOLed; no support will be provided. Python 3.6 should be the minimum required version but is testing on 3.9 and 3.10.

pyngtube requires tkinter, Pygame, PyYAML, and PyAudio. Fairly hefty requirements for what it does. You can get a simplified rundown in requirements.txt.

Installation should be fairly simple. The most direct approach is to install the pre-requisites using Pip like so.

pip install -r requirements.txt

However good housekeeping requires creating a Python Virtualenv for the pre-reqs. Virtualenvs are a good thing to know if you use Python code in any capacity, but a short rundown of how to do this:

Linux

python -m venv pyngtube-env
source pyngtube-env/bin/activate
pip install -r requirements.txt

Windows

python -m venv pyngtube-env
pyngtube-env\Scripts\activate
pip install -r requirements.txt

If you utilized a virtualenv, you will need to activate it before launching pyngtube to make sure you're using the environment properly.

If you run into build errors at the pip install step you're likely on an OS that requires building python libs from scratch. Hopefully this means you're on Linux and have some inkling of how to proceed from here. It might just require installing your distro's build tools.

Usage

Basic launching can be accomplished with python main.pyw in the pyngtube dir, or double-clicking the main.pyw file. This should launch a default experience with a very crappy hand-drawn default avatar.

There is no user interface. You can scroll the mousewheel inside the window to change the microphone threshold and can right-click in the window to open a dialog to select a new profile to load. See Configuration below for avatar configuration specs.

Configuration

The main configuration file is ptv.yaml, in the same directory as main.pyw. You may also manually provide a different config file location as an argument to main.pyw.

This file is a standard yaml file of configuration directives. It is recommended that this main config file only include the bare necessities of configuring the program: microphone settings and window size if you need it. Then the avatar settings should be imported via a profile declared with the profile directive.

A profile is a directory that consists of a second configuration yaml file, and all the images needed to make the avatar work. The profile directive should be simply the name of the directory and the yaml file must be named profile.yaml. Pyngtube will attempt to find this profile in the pyngtube installation directory. profile.yaml must declare the images to be used for the avatar.

Troubleshooting

If the app crashes, closes suddenly, or doesn't open at all, the first step is to launch the app from a command line and see if any errors are printed. The only real cause for a launch failure should be a broken config file, which will print an error explaining the problem.

Configuration errors are fatal (causing a forced exit) by design, including invalid keys in the configuration file.

If the terminal outputs errors about your system not being built to support tcl/tk, tkinter, etc, you're likely missing a tcl/tk package. This should only happen under Linux; Windows installs of Python should always support tk.

Known Issues

First and foremost, this is a personal tool I'm making available as an (arguably bad) example and starting point for someone else's personal tool. This means assumptions are made about my environment that may not work in your environment. Certain bugs I may not care about that you do. Here's a list of what I can think of that's a little "off" right now:

• The application is not hardware accelerated, so CPU usage can get a little high (for my taste anyway, 3-5% on my dev box) if you're scaling a small image to a massive one or vise-versa. This is an easy fix with better buffer handling and is on The List
• Due to design praxis of not drawing anything over the capture region to "ruin the magic" of the avatar, there is no visible feedback on threshold changes. You have to trust mousewheeling in the window changes threshold
• For that matter, there's no way to change threshold if you're using a pointing device without a wheel short of editing the config file

• What little debugging and error raising there is prints to the console. This needs to be reworked to raise actual GUI errors
• pyngtube makes the awkward assumption that you have one audio input device. It should work fine even if you don't, but some configuration around this should be provided
• I don't like the dependency on tkinter because it's undisclosed and cannot be put into requirements.txt but the greater evil prior was a depdency on wxPython which has a massive build and install process. Most py installations come with tkinter bundled

Contributing

My Gitea instance is closed to new registrations so contributions aren't really accepted at the moment. If you must submit a code change, let me know and I'll arrange something.

Code is formatted with python-black before commit.

Why The Weird License?

The ACSL most closely aligns with how I want things I create to be used. In a better world I'd license things MIT or even some variant of CC-BY, but I've seen and experienced time and time again that fully open software tends to filter up, benefitting the largest corporations more than the common user. This results in megacorps benefitting while providing nothing in return and, in the worst cases, even demanding FOSS devs perform free labor for them to perform their security audits, investigate their change requests for their specific use cases, and the like.

I hold no illusion that anything I make will ever be important, but I refuse to even put myself in the position where that could occur. Is the ACSL enforceable? That's a matter of test-by-trial. It says what I want to say with my work; that's what matters.