# 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 WxPython, 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-clicing 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 pyngtube.yaml. Pyngtube will search for this file in the following locations in order, taking the first it finds:

* The location provided as the first argument to main.pyw
* %HOME%/.pyngtube.yaml
* %HOME%/pyngtube.yaml
* %PWD%/pyngtube.yaml
* (pygntube_dir)/pyngtube.yaml
* Fall back to hardcoded defaults

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.

Profiles can either be animated or not. An animated profile can have a list of images for each state, and will shuffle through them in a loop. Check out how the `default` and `default-animated` profiles differ for more info. The `default-animated` profile uses identical animation frames as merely an example but if you alter the images, you'll see animation.


## 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.


## 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