CustomNBT-Startup

CLI tool to encode custom boot animations for BMW NBT head units.

Converts MP4 videos into the .pdds format used by the NBT system for startup animations.

Requirements

• Python 3.11+
• uv (recommended)
• LZO compression library (system dependency)

Installing LZO

# macOS
brew install lzo

# Debian/Ubuntu
sudo apt install liblzo2-dev

On macOS you need to export the paths so python-lzo can find the headers:

export C_INCLUDE_PATH=$(brew --prefix lzo)/include
export LIBRARY_PATH=$(brew --prefix lzo)/lib

You can add these to your shell profile to make them permanent.

Installation

# Install from PyPI
pip install custom-nbt-startup

# Or with uv
uv pip install custom-nbt-startup

# Or install from source
uv pip install .

Quick Start

# One-liner with uvx (no install needed)
uvx --from custom-nbt-startup nbt-startup encode video.mp4

Usage

# Basic usage — outputs <video_name>.pdds
nbt-startup encode video.mp4

# Custom output path
nbt-startup encode video.mp4 -o boot_animation.pdds

# Custom frame count (default: 150)
nbt-startup encode video.mp4 -n 200

# Custom resolution
nbt-startup encode video.mp4 -W 800 -H 480

Running without installing

# Via uvx (uses the published PyPI package)
uvx --from custom-nbt-startup nbt-startup encode video.mp4

# Via uv run (from a cloned repo)
uv run nbt-startup encode video.mp4

Options

License

MIT