Troubleshooting

Installation

Security warnings (Windows/macOS executables): The executables are unsigned. Windows SmartScreen: Click “More info” → “Run anyway”. macOS Gatekeeper: Right-click → “Open”, or System Settings → Privacy & Security → “Open Anyway”. See Installation for details.

Python version error: Use Python 3.11+ (python3.11 -m pip install -e . or uv pip install -e .)

tttool not found: Install tttool (instructions), check PATH

Port in use: Use different port (ttmp32gme --port 8080)

Permission errors: Use virtual environment or uv pip install --user -e . or pip install --user -e .

Upload Issues

Files won’t upload: Check file size (<500MB), format (MP3/OGG only)
Metadata missing: Edit manually in Library page or re-tag files with Mp3tag

Library Issues

Album missing: Refresh page (F5)
GME creation fails: Check tttool installed, disk space available
OID in use: Choose different OID number (1-999)

Print Issues

OID codes not recognized:

Print at 100% scale, no auto-scaling
Use 1200 DPI or higher
Test with OID table
If test table fails, it’s a printer issue
Try: increase pixels per dot (3 or 4), better paper, graphics mode

Quality issues: Clean print heads, replace ink/toner, use smooth white paper

TipToi Pen

Not detected: Check USB connection, reload library page
Copy fails: Check pen storage space
No audio: Verify GME file copied, OID numbers match

Getting Help

Search GitHub issues or create new issue with:

OS and versions
Error messages
What you tried
For print issues: printer model, whether test table works