beebium-server

What is Beebium?

Beebium is a headless, cycle-accurate BBC Micro emulator with a client-server architecture. The emulator runs as a server process -- one per machine variant (Model B, B+, B+ 128K, B with ROM/RAM board) -- and is driven over gRPC, so front-ends and automation talk to it across a well-defined protocol rather than being wired into the emulation core.

What is this package?

beebium-server is that emulator, shipped as platform wheels. Each wheel carries the built server binaries, the ROMs, the presets and the bundled extensions, so a complete, working BBC Micro emulator installs straight from PyPI -- no system package manager, no compiler, no ROM files to locate by hand:

pip install beebium-server

Installing it also puts the four server binaries on PATH (beebium-model-b and its variants), so the package is useful on its own.

Relationship to beebium

beebium is the Python client that drives a server over gRPC. The two are independent packages -- neither depends on the other -- but they complement each other: with both installed, the client finds this wheel automatically and Beebium.launch() needs no arguments.

pip install beebium beebium-server

Supported platforms

A wheel is published for each of these; pip selects the one matching your machine.

Installation

With uv:

uv add beebium-server            # add to your project
# or, into a plain virtualenv:
uv pip install beebium-server

With pip:

pip install beebium-server

Usually you install it alongside the client, pip install beebium beebium-server.

Usage

Run a server from the command line

Installing the wheel puts one console script per machine variant on PATH. Each starts a headless server that listens for gRPC clients:

# Run a BBC Model B server. Variants: beebium-model-b, beebium-model-b-plus,
# beebium-model-b-plus-128k, beebium-model-b-romram.
beebium-model-b --port 48875
# Initializing BBC Model B...
# Listening on port 48875
# BBC Model B ready. Press Ctrl+C to stop.

With no --port the server picks its default port. Run beebium-model-b --help for the other subcommands (listing extensions, describing presets, capturing a screenshot, and more).

Locate the binaries and data from Python

A tiny, dependency-free API reports where the bundled binaries and data live -- useful for launching a server yourself or pointing other tooling at the ROMs:

import beebium.server

# Where the bundled server binary lives (ensured executable), and its kin.
executable = beebium.server.executable_filepath()        # the model-b binary
print(executable)
print(beebium.server.variants())                         # the four variants
print(beebium.server.rom_dirpath())                      # the bundled ROMs
print(beebium.server.preset_dirpath())                   # the bundled presets
print(beebium.server.__version__)

Drive a server from Python

To control a server programmatically -- type at the keyboard, read the screen, inspect memory, drive the debugger -- install the beebium client and see its documentation. With both packages installed, Beebium.launch() starts one of these servers with no arguments.

Contributing

Development happens in the Beebium repository. This wheel is not built from source here: build_wheel.py repackages a release bundle that the monorepo already builds and validates, so the server binaries are byte-identical to those on the GitHub Release.

This README is generated -- do not edit README.md directly. See CONTRIBUTING.md.

License

GPL-3.0-or-later. See COPYING.txt.