TSC Bridge

A universal thermal label printing bridge. One binary, any printer, any platform.

TSC Bridge connects web applications to thermal label printers through a local HTTP API. It runs as a system tray application, receives print jobs over localhost, and sends them to the printer using the appropriate label language (TSPL, ZPL, EPL, and more through community drivers).

Releases | Documentation | Contributing

Features

Single binary -- no runtime, no installer, no database
Cross-platform -- macOS (arm64), Windows (amd64, i386), Linux (amd64)
Native UI -- system tray icon with embedded dashboard window
HTTP API -- plain JSON over localhost, CORS-aware
Label designer -- interactive drag-and-drop editor in the dashboard
Batch printing -- import Excel/CSV, map columns to fields, print hundreds
PDF output -- vector PDF generation with TrueType fonts
Driver architecture -- extensible support for multiple printer brands
QR and barcodes -- Code 128, Code 39, EAN-13, UPC-A, QR codes, vCards
Auto-DPI detection -- reads printer capabilities on macOS and Windows
USB direct printing -- bypasses the OS print spooler via libusb
TLS on localhost -- self-signed certificate for HTTPS origins
Whitelabel -- custom branding (name, logo, colors) per deployment

Install

macOS

Download the DMG from the releases page, open it, and drag TSC Bridge.app to your Applications folder.

Or install the raw binary:

curl -fsSL https://github.com/nicoyarce/tsc-bridge/releases/latest/download/tsc-bridge-mac -o /usr/local/bin/tsc-bridge
chmod +x /usr/local/bin/tsc-bridge

Windows

Download tsc-bridge-win-<version>.zip from the releases page. Extract and run install_windows.bat as administrator, or compile tsc-bridge.iss with InnoSetup for a GUI installer.

Linux

curl -fsSL https://github.com/nicoyarce/tsc-bridge/releases/latest/download/tsc-bridge-linux-amd64 -o /usr/local/bin/tsc-bridge
chmod +x /usr/local/bin/tsc-bridge

On Linux, you may need to add your user to the lp group for USB printer access:

sudo usermod -aG lp $USER

Quick Start

Start the bridge:

tsc-bridge

The system tray icon appears. Click it and select Dashboard to open the native window.
Send a print job from your web application:

curl -X POST http://127.0.0.1:9638/print \
  -H "Content-Type: application/json" \
  -d '{
    "printer": "TSC_TDP-244_Plus",
    "data": "SIZE 50 mm, 30 mm\nGAP 3 mm, 0 mm\nCLS\nTEXT 10,10,\"3\",0,1,1,\"Hello World\"\nPRINT 1,1\n"
  }'

How It Works

graph TD
    A[Web Application] -->|HTTP POST JSON| B[TSC Bridge]
    B --> C[HTTP Server]
    B --> D[Label Renderer]
    B --> E[Driver Layer]
    D -->|PDF / TSPL / ZPL / EPL| E
    E -->|USB / CUPS / Win32 RAW| F[Thermal Printer]

The bridge runs on 127.0.0.1:9638 (configurable). Web applications send label data as JSON. The bridge renders the label using the appropriate driver and sends the raw commands to the printer.

API Reference

All endpoints accept and return JSON. The base URL is http://127.0.0.1:9638.

`GET /status`

Returns bridge status, connected printers, and version.

`GET /printers`

Lists all detected printers with type, status, and capabilities.

`POST /print`

Sends a raw print job. Body: { "printer": "name", "data": "TSPL commands" }.

`POST /batch-pdf`

Generates a multi-page PDF from a template and row data. Body: { "template_id": "uuid", "rows": [...], "mapping": {...} }.

Query parameter ?mode=url returns a download URL instead of the binary file.

`POST /batch-tspl`

Generates TSPL commands from a template and prints them. Body: { "template_id": "uuid", "rows": [...], "printer": "name" }.

Modes: print (default), preview (returns TSPL text), raster (bitmap).

`GET /dashboard`

Serves the embedded HTML dashboard.

`GET /output/{filename}`

Serves generated files (PDF, images). Add ?dl=1 to force download.

For the complete API reference, see docs/API.md.

Label Format

TSC Bridge uses a JSON-based label format inspired by pdfme. The format describes page dimensions, field positions, types, and variable bindings.

{
  "basePdf": { "width": 50, "height": 30 },
  "schemas": [
    [
      {
        "name": "product_name",
        "type": "text",
        "position": { "x": 5, "y": 5 },
        "width": 40,
        "height": 8,
        "fontSize": 12,
        "fontName": "Helvetica"
      },
      {
        "name": "barcode",
        "type": "barcodes128",
        "position": { "x": 5, "y": 15 },
        "width": 40,
        "height": 10
      }
    ]
  ]
}

Field types: text, multiVariableText, qrcode, barcodes128, barcodes39, image, line, rectangle.

For the complete specification, see docs/LABEL_STANDARD.md.

Drivers

TSC Bridge uses a driver architecture to support multiple printer brands and label languages. Each driver translates the universal label format into printer-specific commands.

Built-in Drivers

Driver	Language	Printers
TSPL	TSPL2	TSC TDP-244, TTP-245, TE200, TE300 series
PDF	PDF 1.4	Any printer via OS print dialog

Community Drivers (planned)

Driver	Language	Printers	Status
ZPL	ZPL II	Zebra ZD, ZT, GK, GX series	Seeking contributors
EPL	EPL2	Zebra LP, TLP legacy series	Seeking contributors
CPCL	CPCL	Zebra mobile printers	Seeking contributors
ESC/POS	ESC/POS	Epson, Star, Bixolon receipt printers	Seeking contributors
DPL	DPL	Datamax-O'Neil / Honeywell	Seeking contributors
SBPL	SBPL	SATO printers	Seeking contributors
Fingerprint	Fingerprint	Intermec / Honeywell	Seeking contributors

To write a new driver, see docs/DRIVERS.md.

Documentation

Architecture -- system design and component overview
Goals -- project priorities and non-goals
Label Standard -- label format specification
Driver Guide -- how to write a printer driver
API Reference -- complete HTTP API documentation
Changelog -- version history
Contributing -- how to contribute
Security -- vulnerability reporting
Code of Conduct -- community guidelines

Building from Source

Prerequisites

Go 1.21 or later
CGO enabled (required for system tray and USB)
macOS: Xcode Command Line Tools, brew install libusb
Windows: MinGW-w64
Linux: apt install libusb-1.0-0-dev libgtk-3-dev libappindicator3-dev

Build

git clone https://github.com/nicoyarce/tsc-bridge.git
cd tsc-bridge

# macOS
make build-mac

# Windows (from Windows or with MinGW cross-compiler)
make build-windows

# Linux
go build -o tsc-bridge .

Test

go test ./...

Full Release Build

The build.sh script builds all platforms, generates icons, creates the macOS .app bundle and DMG, and packages the Windows installer:

./build.sh

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines. The most impactful way to contribute is by writing a driver for a printer brand you have access to.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.github		.github
certs		certs
docs		docs
testdata		testdata
.editorconfig		.editorconfig
.gitignore		.gitignore
.golangci.yml		.golangci.yml
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
GOALS.md		GOALS.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
api_client.go		api_client.go
auth.go		auth.go
auth_test.go		auth_test.go
autostart_darwin.go		autostart_darwin.go
autostart_other.go		autostart_other.go
autostart_windows.go		autostart_windows.go
batch.go		batch.go
browser.go		browser.go
build.sh		build.sh
certs_embed.go		certs_embed.go
com.tsc-bridge.plist		com.tsc-bridge.plist
config.go		config.go
config_test.go		config_test.go
crypto.go		crypto.go
dashboard.go		dashboard.go
dashboard.html		dashboard.html
download_server.go		download_server.go
dpi.go		dpi.go
dpi_darwin.go		dpi_darwin.go
dpi_other.go		dpi_other.go
dpi_test.go		dpi_test.go
dpi_windows.go		dpi_windows.go
driver.go		driver.go
driver_darwin.go		driver_darwin.go
driver_other.go		driver_other.go
driver_windows.go		driver_windows.go
excel.go		excel.go
filedialog.go		filedialog.go
go.mod		go.mod
go.sum		go.sum
icon.go		icon.go
icon_darwin.go		icon_darwin.go
icon_other.go		icon_other.go
icon_windows.go		icon_windows.go
install_mac.sh		install_mac.sh
install_windows.bat		install_windows.bat
kill_other.go		kill_other.go
kill_windows.go		kill_windows.go
label_template.go		label_template.go
main.go		main.go
msgbox_other.go		msgbox_other.go
msgbox_windows.go		msgbox_windows.go
network.go		network.go
pdf_renderer.go		pdf_renderer.go
pdf_upload.go		pdf_upload.go
presets.go		presets.go
printer_crossbuild.go		printer_crossbuild.go
printer_other.go		printer_other.go
printer_windows.go		printer_windows.go
share.go		share.go
tls.go		tls.go
tray.go		tray.go
tsc-bridge.iss		tsc-bridge.iss
tspl_renderer.go		tspl_renderer.go
webview.go		webview.go
webview_darwin.go		webview_darwin.go
webview_stub.go		webview_stub.go

Folders and files

Latest commit

History

Repository files navigation

TSC Bridge

Table of Contents

Features

Install

macOS

Windows

Linux

Quick Start

How It Works

API Reference

GET /status

GET /printers

POST /print

POST /batch-pdf

POST /batch-tspl

GET /dashboard

GET /output/{filename}

Label Format

Drivers

Built-in Drivers

Community Drivers (planned)

Documentation

Building from Source

Prerequisites

Build

Test

Full Release Build

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`GET /status`

`GET /printers`

`POST /print`

`POST /batch-pdf`

`POST /batch-tspl`

`GET /dashboard`

`GET /output/{filename}`

Packages