PiDVD

PiDVD is a small Linux appliance for playing DVD-Video ISO images on a Raspberry Pi 3 or Raspberry Pi 4. It is built for standard-definition CRT displays and other equipment that accepts 15 kHz video.

The project uses the DVD's native raster and field timing. It does not scale a movie to a desktop resolution and then convert it back to standard definition. During playback it produces 480i at 59.94 fields per second for NTSC material or 576i at 50 fields per second for PAL material. The library menu normally runs at 240p.

PiDVD is a complete SD card image built with Buildroot. It contains a custom C player, a simple local library interface, a web remote, Raspberry Pi kernel patches, and separate boot configurations for composite and HDMI output.

Who this is for

PiDVD may be useful if you:

keep DVD-Video backups as ISO files and want to play them without a desktop computer;
use a CRT television, broadcast monitor, RGB converter, or other 15 kHz display equipment;
care about preserving DVD field order, interlacing, cadence, and standard-definition timing;
want a small player that boots directly into a local library instead of a desktop;
are studying Linux DRM/KMS, Raspberry Pi video timing, Buildroot, or DVD navigation.

It is probably not the right project if you want a streaming box, a general media center, Blu-ray playback, arbitrary video file support, or conventional 480p, 720p, or 1080p HDMI output.

What it does

Plays DVD-Video ISO images.
Supports DVD menus, titles, chapters, audio stream selection, subtitles, and resume positions.
Reads the disc's video system from DVD navigation data and switches between native NTSC and PAL playback modes.
Outputs composite video directly from the Raspberry Pi analog video connector.
Outputs 15 kHz timings over HDMI for use with suitable HDMI-to-VGA and RGB conversion hardware.
Decodes MPEG-2 video in software.
Decodes AC-3 audio to stereo PCM.
Passes AC-3 or DTS through as IEC 61937 when GPIO S/PDIF is available and selected.
Provides a local picker for browsing ISO files on USB storage.
Saves output, audio, display, theme, and resume settings.
Accepts USB keyboards and common USB HID media remotes.
Provides an unauthenticated web remote on the local network.
Can copy a DVD from an attached USB optical drive to writable USB storage through the local interface.

Supported boards

Board	Image target	Composite	HDMI	GPIO S/PDIF
Raspberry Pi 3 Model B or B+	Pi 3	Yes	Yes, through a 15 kHz-compatible conversion chain	Yes, GPIO 21
Raspberry Pi 4 Model B	Pi 4	Yes	Yes, HDMI0 only	Not currently supported with video-clock locking

The Pi 3 and Pi 4 use different kernels, device trees, firmware files, and boot configurations. Always build and flash the image for the board you are using.

Both targets are 32-bit ARM systems. The Pi 4 target uses the BCM2711 kernel configuration but keeps the same 32-bit player environment as the Pi 3 target.

Video connections

Composite

Composite video is the shipped default. Connect a Raspberry Pi-compatible TRRS cable to the board's analog audio/video jack. The Raspberry Pi pin order is:

Contact	Signal
Tip	Left audio
Ring 1	Right audio
Ring 2	Ground
Sleeve	Composite video

Many camcorder cables use a different pin order even though the plug fits. A wrong cable can produce no picture while the DRM connector and video hardware appear to be working normally.

HDMI and RGB

PiDVD's HDMI mode is intended for a 15 kHz conversion chain such as:

Raspberry Pi HDMI
    -> HDMI-to-VGA converter
    -> UMSA or another sync and level converter
    -> SCART RGB or compatible 15 kHz display

The HDMI output uses DVD and picker timings rather than normal computer monitor modes. Some televisions, capture devices, HDMI switches, and inexpensive converters reject 240p or interlaced standard-definition timings.

On a Raspberry Pi 4, use the micro-HDMI connector nearest the USB-C power connector. This is HDMI0. The second micro-HDMI connector is disabled by the PiDVD boot configuration.

On a Raspberry Pi 3, use its single full-size HDMI connector.

Do not connect a 15 kHz analog RGB signal directly to a VGA monitor unless the monitor explicitly supports it.

Audio connections

PiDVD can send stereo PCM to:

a USB audio device;
the Raspberry Pi analog audio jack;
GPIO S/PDIF on a Raspberry Pi 3.

The player treats video as the master clock. For USB and analog PCM output it uses adaptive resampling to keep audio aligned with displayed fields without accumulating drift.

On the Pi 3, the GPIO S/PDIF output uses GPIO 21, physical header pin 40. The Pi 3 kernel contains a clock patch that derives the S/PDIF clock from the same source as video. This path can carry stereo PCM or IEC 61937 AC-3/DTS passthrough.

The equivalent video-locked GPIO S/PDIF clock path is not implemented for the Pi 4. Use USB or analog audio on Pi 4 for now. DTS software decoding is not included, so DTS requires passthrough on a supported output.

How it works

System image

Buildroot creates a small Linux system containing only the packages, services, firmware, and kernel features needed by PiDVD. The generated SD card image has:

a FAT boot partition with Raspberry Pi firmware, the kernel, device trees, and output-specific boot files;
an ext4 root partition containing the player and its libraries;
init scripts that start the player, wired networking, SSH, and the web remote.

The main services are:

Service	Purpose
`S30pidvd`	Starts `pidvd-player --ui`
`S40network`	Requests an IPv4 address on Ethernet with DHCP
`S45pidvd-remote`	Starts the HTTP remote on port 8080

Playback pipeline

The player reads DVD navigation and sector data with libdvdread and libdvdnav. Its MPEG program-stream demultiplexer sends video to libmpeg2, audio to liba52 or the passthrough path, and subpictures to the player's subtitle and menu overlay code.

Decoded video is written to DRM framebuffers and submitted to the Raspberry Pi VC4 driver through atomic KMS. The field scheduler follows the MPEG-2 top_field_first and repeat_first_field flags. This preserves interlaced field order and film cadence, including native 3:2 cadence for NTSC film material.

DVD-Video ISO
    -> libdvdread and libdvdnav
    -> MPEG program-stream demultiplexer
       -> libmpeg2 video decode
       -> AC-3 decode or AC-3/DTS passthrough
       -> DVD subpicture and menu overlay
    -> field scheduler
    -> VC4 DRM/KMS
    -> composite VEC or HDMI0

The kernel includes two shared VC4 patches. They make the DRM vblank sequence advance once per physical interlaced field and prevent the generic DRM code from halving that field rate. The Pi 3 also has a separate video-clock patch for GPIO S/PDIF. The Pi 4 kernel builds the BCM2711 HDMI DDC controller into the kernel so the HDMI connector can complete probing during boot.

Output switching

The boot partition contains separate files for each video path:

config-composite.txt and cmdline-composite.txt;
config-hdmi.txt and cmdline-hdmi.txt;
active copies named config.txt and cmdline.txt.

Changing the output in PiDVD's settings copies the selected pair to the active names and reboots the board. A reboot is required because composite and HDMI use different device-tree configurations.

On Pi 4, composite uses the VC4 VEC attached to pixel valve 3. HDMI uses HDMI0 and its DDC controller. These details differ from Pi 3, which is why PiDVD has separate board images.

Storage and settings

At startup the picker looks for a USB storage device and mounts it at /media/usb. exFAT is recommended because a DVD ISO can be larger than FAT32's 4 GB file limit. Keep each movie as a complete .iso file. Folders may be used to organize the library.

Settings and resume information are stored in /boot/pidvd.cfg. This keeps them separate from removable media and lets them survive root filesystem replacement during development.

Hardware needed

For a basic composite setup:

Raspberry Pi 3 Model B/B+ or Raspberry Pi 4 Model B;
a suitable power supply;
microSD card, 1 GB or larger;
Raspberry Pi-compatible composite cable;
USB storage containing DVD-Video ISO files;
USB keyboard or HID media remote.

For the web remote or SSH, also use a wired Ethernet connection to a network with DHCP.

For HDMI/RGB output, add a converter chain that accepts PiDVD's 15 kHz timings. For Pi 4, the first connection from the board must use the HDMI0 micro-HDMI port nearest USB-C power.

A stable supply matters. If dmesg reports Undervoltage detected, replace the supply or cable before diagnosing video or storage problems.

Build requirements

The full image build runs in Docker. Install:

Docker Desktop on macOS, or Docker Engine on Linux;
a POSIX shell;
Git;
enough free disk space for Buildroot sources, the cross toolchain, and build products.

The first build downloads Buildroot 2025.02.3 and package sources. Later builds reuse a Docker image and a named Docker volume called pidvd-build.

Clone the repository and enter it:

git clone https://github.com/WeebLabs/PiDVD.git
cd PiDVD

Build an SD card image

Raspberry Pi 3

./scripts/build-image.sh

The image is written to:

output/images/sdcard.img

Raspberry Pi 4

./scripts/build-image.sh pi4

The image is written to:

output/images/pidvd-pi4.img

The script uses all available CPU cores by default. Set JOBS if you need to limit parallel compilation:

JOBS=4 ./scripts/build-image.sh pi4

Build output is generated locally and is not intended to be committed.

Flash the image

Raspberry Pi Imager is the simplest option:

Open Raspberry Pi Imager.
Choose the option to use a custom operating system image.
Select sdcard.img for Pi 3 or pidvd-pi4.img for Pi 4.
Select the correct microSD card.
Write the image and let the application verify it.
Eject the card cleanly.

Any raw image writer can be used. Be certain that the destination is the microSD card. Writing a raw image to the wrong disk destroys the data on that disk.

The image already contains PiDVD's boot files. Do not use Raspberry Pi Imager's operating-system customization to replace config.txt, enable Wi-Fi, or change boot options.

Prepare the media drive

Format a USB storage device as exFAT.
Copy DVD-Video ISO files to it.
Use folders if you want to group the files.
Eject the drive cleanly before connecting it to the Pi.

FAT32 is not recommended because larger DVD images do not fit in a single file. A damaged or unclean filesystem can delay startup or prevent the library from appearing.

First boot

Insert the flashed microSD card.
Connect composite video, or prepare the boot partition for HDMI as described below.
Connect the USB media drive and a keyboard or remote.
Connect Ethernet if you want DHCP, the web remote, or SSH.
Apply power.

The shipped image starts in composite mode. The local picker starts automatically. If the media drive was recognized, the picker displays folders and ISO files from /media/usb.

To start with HDMI before the first boot, mount the FAT boot partition on another computer and replace the active boot files with the HDMI variants:

cp config-hdmi.txt config.txt
cp cmdline-hdmi.txt cmdline.txt

Run those commands from the mounted boot partition. On Pi 4, connect the display chain to HDMI0, the port nearest USB-C power.

After the picker is running, output can be changed from its settings screen. PiDVD updates the boot files and reboots.

Controls

Common keyboard controls are:

Key	Action
Arrow keys	Move or navigate
Enter	Select or DVD menu OK
Escape or `B`	Back
`M`	DVD menu
`T`	DVD title menu
Space	Play or pause
`S`	Stop
`N` or Page Down	Next chapter
`P` or Page Up	Previous chapter
`A`	Change audio stream
`C`	Change subtitle stream
`G`	Open settings
`E`	Open library edit actions
Media volume keys	Change volume or mute

HID remotes that report standard navigation, playback, chapter, and volume keys should work through Linux evdev. Exact key assignments vary between remotes.

Test pattern generator

Open Settings, select the Tools tab, then open Test Patterns. The generator provides the calibration patterns found in the pattern menu of the 240p Test Suite PS1 port:

PLUGE;
color bars;
SMPTE color bars for NTSC or EBU color bars for PAL;
color bars with a gray reference;
color bleed check;
grid;
linearity circles;
gray ramp;
full-field white, black, red, green, and blue screens;
sharpness patterns;
convergence and focus patterns;
adjustable overscan borders.

The patterns are drawn by PiDVD at its native 720-sample 240p or 288p menu timing. They do not use imported code or bitmap assets from the PS1 project. PiDVD temporarily disables its composite low-pass filter while the generator is open so the sharpness and color-bleed patterns reach the output unchanged.

In the pattern list, use Up and Down to select a row, Left and Right to change columns, Enter to open a pattern, and Back to close the tool. While a pattern is open, Left and Right move between patterns. Up, Down, or Enter changes the current pattern variant. The title and controls disappear after a short delay to leave a clean raster. Press Back to return to the pattern list.

Network access

PiDVD configures wired Ethernet with DHCP. It does not include a Wi-Fi setup interface.

The boot log prints the assigned address when networking starts. You can also find the address in your router's DHCP client list.

Web remote

Open this address from another device on the same network:

http://<pi-address>:8080/

The remote sends commands to the same control interface used by local input. It has no login or TLS. Keep PiDVD on a trusted local network and do not expose port 8080 directly to the internet.

SSH

The development image runs Dropbear SSH with these default credentials:

user: root
password: pidvd

These credentials are public and are intended for development on a trusted network. Change the root password or restrict network access if the device will remain connected.

The serial console is also enabled at 115200 baud.

Build host utilities and tests

The full player depends on Linux DRM and Raspberry Pi behavior, but the repository also contains host-side tools and unit tests.

On macOS, install the DVD reading library and build with CMake:

brew install libdvdread
cmake -S player -B player/build -DBUILD_TESTING=ON
cmake --build player/build
ctest --test-dir player/build --output-on-failure

Inspect an ISO without starting the player:

player/build/dvdinfo /path/to/movie.iso

On Linux, install CMake, a C compiler, pkg-config, and the development package for libdvdread, then use the same CMake commands.

Repository layout

Path	Contents
`player/`	Player, picker, web remote, host utilities, and tests
`buildroot/`	Buildroot configurations, kernel patches, board files, packages, and root filesystem overlay
`docker/`	Reproducible Buildroot build environment
`scripts/`	Image build and development helper scripts
`docs/`	Architecture, timing, UI, and development notes
`output/`	Generated images and local build products

The Pi 3 and Pi 4 defconfigs are:

buildroot/configs/pidvd_defconfig
buildroot/configs/pidvd_pi4_defconfig

Shared VC4 changes are under buildroot/kernel-patches/common/. Board-specific kernel changes are under buildroot/kernel-patches/pi3/ and buildroot/kernel-patches/pi4/.

Troubleshooting

Composite connector is present but the screen is blank

Check the cable first. A cable with the wrong TRRS pin order can leave the Pi and kernel looking healthy while no composite signal reaches the television.

Then confirm that the composite boot files are active and inspect DRM state:

cat /proc/cmdline
ls -l /sys/class/drm
for connector in /sys/class/drm/card*-*; do
    test -f "$connector/status" || continue
    echo "$connector"
    cat "$connector/status"
    cat "$connector/modes" 2>/dev/null
done

The connector should appear as card0-Composite-1 and report connected after the player enables it.

HDMI has no `/dev/dri/card0`

Make sure the HDMI boot variants are active. On Pi 4, make sure the cable is in HDMI0, nearest the USB-C power connector. A working boot should show HDMI components binding to the VC4 DRM device.

dmesg | grep -Ei 'hdmi|vc4|drm|i2c|deferred'
ls -l /dev/dri /sys/class/drm

The Pi 4 image builds i2c-brcmstb into the kernel because HDMI DDC is required before the DRM device can finish probing. If an older image repeatedly logs only the HVS binding and ends with deferred probe pending, rebuild and flash the current Pi 4 image.

If DRM is present but the display remains blank, test the converter without an HDMI switch or capture device in the path. Confirm that it accepts 240p and 480i/576i timings.

No USB library appears

Check that the drive was detected and mounted:

dmesg | tail -100
mount | grep /media/usb
ls -la /media/usb

Use a cleanly unmounted exFAT filesystem. Try a powered USB hub if a hard drive or optical drive draws more current than the Pi can supply reliably.

No network address appears

PiDVD only configures eth0. Check the cable, router link, and DHCP state:

ip addr show eth0
dmesg | grep -Ei 'eth0|link is'

The system reports undervoltage

Use a known-good Raspberry Pi power supply and a short, suitable power cable. Undervoltage can affect USB storage, Ethernet, and video even if the board continues to boot.

General video diagnostics

These commands provide a useful first report:

cat /proc/cmdline
dmesg | grep -Ei 'vc4|drm|vec|hdmi|voltage'
ls -l /sys/class/drm

When the player is running, its video log identifies the selected connector, mode, pixel clock, field parity, and composite filter.

Current limitations

Playback is for DVD-Video ISO images, not individual MPEG files, Blu-ray images, or streaming services.
Video decode is software-based.
HDMI compatibility depends on the display and converter accepting 15 kHz standard-definition modes.
Pi 4 supports USB and analog audio, but not the Pi 3 video-locked GPIO S/PDIF implementation.
DTS requires passthrough and is not decoded to PCM.
Networking is wired DHCP only.
The web remote and default SSH account are not hardened for an untrusted network.
The image has separate Pi 3 and Pi 4 targets. It is not a single image that detects either board.

Name		Name	Last commit message	Last commit date
Latest commit History 74 Commits
buildroot		buildroot
docker		docker
docs		docs
player		player
scripts		scripts
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation