custom-nbt-startup 0.1.1

CLI tool to encode/decode BMW NBT boot animation (.pdds) files

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

Option	Description
-o, --output	Output .pdds file path (default: <input_stem>.pdds)
-n, --frames	Number of frames to extract (default: 150)
-W, --width	Frame width in pixels (default: 1280, must be multiple of 4)
-H, --height	Frame height in pixels (default: 480, must be multiple of 4)
--version	Show version
--help	Show help

License

MIT