{"id":48088878,"url":"https://github.com/mherrera53/labelctl","last_synced_at":"2026-04-04T15:26:30.848Z","repository":{"id":343099360,"uuid":"1176279236","full_name":"mherrera53/labelctl","owner":"mherrera53","description":"HTTP bridge for thermal label printers. Print from any browser to TSC, Zebra, and TSPL/ZPL printers over USB or network. Cross-platform (macOS, Windows, Linux).","archived":false,"fork":false,"pushed_at":"2026-03-08T22:18:13.000Z","size":293,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-09T01:55:22.622Z","etag":null,"topics":["barcode","barcode-printer","cross-platform","escpos","golang","http-api","label-printer","label-printing","pdfme","print-server","printer-driver","qrcode","thermal-printer","thermal-printing","tsc-printer","tspl","tspl2","usb-printing","zebra-printer","zpl"],"latest_commit_sha":null,"homepage":"https://labelctl.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mherrera53.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-08T21:11:54.000Z","updated_at":"2026-03-08T22:18:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mherrera53/labelctl","commit_stats":null,"previous_names":["mherrera53/labelctl"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mherrera53/labelctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mherrera53%2Flabelctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mherrera53%2Flabelctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mherrera53%2Flabelctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mherrera53%2Flabelctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mherrera53","download_url":"https://codeload.github.com/mherrera53/labelctl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mherrera53%2Flabelctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31403958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["barcode","barcode-printer","cross-platform","escpos","golang","http-api","label-printer","label-printing","pdfme","print-server","printer-driver","qrcode","thermal-printer","thermal-printing","tsc-printer","tspl","tspl2","usb-printing","zebra-printer","zpl"],"created_at":"2026-04-04T15:26:30.352Z","updated_at":"2026-04-04T15:26:30.761Z","avatar_url":"https://github.com/mherrera53.png","language":"Go","readme":"# TSC Bridge\n\nA universal thermal label printing bridge. One binary, any printer, any\nplatform.\n\nTSC Bridge connects web applications to thermal label printers through a local\nHTTP API. It runs as a system tray application, receives print jobs over\n`localhost`, and sends them to the printer using the appropriate label language\n(TSPL, ZPL, EPL, and more through community drivers).\n\n[Releases](https://github.com/nicoyarce/tsc-bridge/releases) |\n[Documentation](#documentation) |\n[Contributing](CONTRIBUTING.md)\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n- [API Reference](#api-reference)\n- [Label Format](#label-format)\n- [Drivers](#drivers)\n- [Documentation](#documentation)\n- [Building from Source](#building-from-source)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- **Single binary** -- no runtime, no installer, no database\n- **Cross-platform** -- macOS (arm64), Windows (amd64, i386), Linux (amd64)\n- **Native UI** -- system tray icon with embedded dashboard window\n- **HTTP API** -- plain JSON over localhost, CORS-aware\n- **Label designer** -- interactive drag-and-drop editor in the dashboard\n- **Batch printing** -- import Excel/CSV, map columns to fields, print hundreds\n- **PDF output** -- vector PDF generation with TrueType fonts\n- **Driver architecture** -- extensible support for multiple printer brands\n- **QR and barcodes** -- Code 128, Code 39, EAN-13, UPC-A, QR codes, vCards\n- **Auto-DPI detection** -- reads printer capabilities on macOS and Windows\n- **USB direct printing** -- bypasses the OS print spooler via libusb\n- **TLS on localhost** -- self-signed certificate for HTTPS origins\n- **Whitelabel** -- custom branding (name, logo, colors) per deployment\n\n## Install\n\n### macOS\n\nDownload the DMG from the\n[releases page](https://github.com/nicoyarce/tsc-bridge/releases), open it,\nand drag **TSC Bridge.app** to your Applications folder.\n\nOr install the raw binary:\n\n```sh\ncurl -fsSL https://github.com/nicoyarce/tsc-bridge/releases/latest/download/tsc-bridge-mac -o /usr/local/bin/tsc-bridge\nchmod +x /usr/local/bin/tsc-bridge\n```\n\n### Windows\n\nDownload `tsc-bridge-win-\u003cversion\u003e.zip` from the releases page. Extract and run\n`install_windows.bat` as administrator, or compile `tsc-bridge.iss` with\n[InnoSetup](https://jrsoftware.org/isinfo.php) for a GUI installer.\n\n### Linux\n\n```sh\ncurl -fsSL https://github.com/nicoyarce/tsc-bridge/releases/latest/download/tsc-bridge-linux-amd64 -o /usr/local/bin/tsc-bridge\nchmod +x /usr/local/bin/tsc-bridge\n```\n\nOn Linux, you may need to add your user to the `lp` group for USB printer\naccess:\n\n```sh\nsudo usermod -aG lp $USER\n```\n\n## Quick Start\n\n1. Start the bridge:\n\n```sh\ntsc-bridge\n```\n\n2. The system tray icon appears. Click it and select **Dashboard** to open the\n   native window.\n\n3. Send a print job from your web application:\n\n```sh\ncurl -X POST http://127.0.0.1:9638/print \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"printer\": \"TSC_TDP-244_Plus\",\n    \"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\"\n  }'\n```\n\n## How It Works\n\n```mermaid\ngraph TD\n    A[Web Application] --\u003e|HTTP POST JSON| B[TSC Bridge]\n    B --\u003e C[HTTP Server]\n    B --\u003e D[Label Renderer]\n    B --\u003e E[Driver Layer]\n    D --\u003e|PDF / TSPL / ZPL / EPL| E\n    E --\u003e|USB / CUPS / Win32 RAW| F[Thermal Printer]\n```\n\nThe bridge runs on `127.0.0.1:9638` (configurable). Web applications send\nlabel data as JSON. The bridge renders the label using the appropriate driver\nand sends the raw commands to the printer.\n\n## API Reference\n\nAll endpoints accept and return JSON. The base URL is `http://127.0.0.1:9638`.\n\n### `GET /status`\n\nReturns bridge status, connected printers, and version.\n\n### `GET /printers`\n\nLists all detected printers with type, status, and capabilities.\n\n### `POST /print`\n\nSends a raw print job. Body: `{ \"printer\": \"name\", \"data\": \"TSPL commands\" }`.\n\n### `POST /batch-pdf`\n\nGenerates a multi-page PDF from a template and row data. Body:\n`{ \"template_id\": \"uuid\", \"rows\": [...], \"mapping\": {...} }`.\n\nQuery parameter `?mode=url` returns a download URL instead of the binary file.\n\n### `POST /batch-tspl`\n\nGenerates TSPL commands from a template and prints them. Body:\n`{ \"template_id\": \"uuid\", \"rows\": [...], \"printer\": \"name\" }`.\n\nModes: `print` (default), `preview` (returns TSPL text), `raster` (bitmap).\n\n### `GET /dashboard`\n\nServes the embedded HTML dashboard.\n\n### `GET /output/{filename}`\n\nServes generated files (PDF, images). Add `?dl=1` to force download.\n\nFor the complete API reference, see [docs/API.md](docs/API.md).\n\n## Label Format\n\nTSC Bridge uses a JSON-based label format inspired by\n[pdfme](https://pdfme.com/). The format describes page dimensions, field\npositions, types, and variable bindings.\n\n```json\n{\n  \"basePdf\": { \"width\": 50, \"height\": 30 },\n  \"schemas\": [\n    [\n      {\n        \"name\": \"product_name\",\n        \"type\": \"text\",\n        \"position\": { \"x\": 5, \"y\": 5 },\n        \"width\": 40,\n        \"height\": 8,\n        \"fontSize\": 12,\n        \"fontName\": \"Helvetica\"\n      },\n      {\n        \"name\": \"barcode\",\n        \"type\": \"barcodes128\",\n        \"position\": { \"x\": 5, \"y\": 15 },\n        \"width\": 40,\n        \"height\": 10\n      }\n    ]\n  ]\n}\n```\n\nField types: `text`, `multiVariableText`, `qrcode`, `barcodes128`,\n`barcodes39`, `image`, `line`, `rectangle`.\n\nFor the complete specification, see\n[docs/LABEL_STANDARD.md](docs/LABEL_STANDARD.md).\n\n## Drivers\n\nTSC Bridge uses a driver architecture to support multiple printer brands and\nlabel languages. Each driver translates the universal label format into\nprinter-specific commands.\n\n### Built-in Drivers\n\n| Driver | Language | Printers |\n|--------|----------|----------|\n| TSPL   | TSPL2    | TSC TDP-244, TTP-245, TE200, TE300 series |\n| PDF    | PDF 1.4  | Any printer via OS print dialog |\n\n### Community Drivers (planned)\n\n| Driver | Language | Printers | Status |\n|--------|----------|----------|--------|\n| ZPL    | ZPL II   | Zebra ZD, ZT, GK, GX series | Seeking contributors |\n| EPL    | EPL2     | Zebra LP, TLP legacy series | Seeking contributors |\n| CPCL   | CPCL     | Zebra mobile printers | Seeking contributors |\n| ESC/POS| ESC/POS  | Epson, Star, Bixolon receipt printers | Seeking contributors |\n| DPL    | DPL      | Datamax-O'Neil / Honeywell | Seeking contributors |\n| SBPL   | SBPL     | SATO printers | Seeking contributors |\n| Fingerprint | Fingerprint | Intermec / Honeywell | Seeking contributors |\n\nTo write a new driver, see [docs/DRIVERS.md](docs/DRIVERS.md).\n\n## Documentation\n\n- [Architecture](ARCHITECTURE.md) -- system design and component overview\n- [Goals](GOALS.md) -- project priorities and non-goals\n- [Label Standard](docs/LABEL_STANDARD.md) -- label format specification\n- [Driver Guide](docs/DRIVERS.md) -- how to write a printer driver\n- [API Reference](docs/API.md) -- complete HTTP API documentation\n- [Changelog](CHANGELOG.md) -- version history\n- [Contributing](CONTRIBUTING.md) -- how to contribute\n- [Security](SECURITY.md) -- vulnerability reporting\n- [Code of Conduct](CODE_OF_CONDUCT.md) -- community guidelines\n\n## Building from Source\n\n### Prerequisites\n\n- Go 1.21 or later\n- CGO enabled (required for system tray and USB)\n- macOS: Xcode Command Line Tools, `brew install libusb`\n- Windows: MinGW-w64\n- Linux: `apt install libusb-1.0-0-dev libgtk-3-dev libappindicator3-dev`\n\n### Build\n\n```sh\ngit clone https://github.com/nicoyarce/tsc-bridge.git\ncd tsc-bridge\n\n# macOS\nmake build-mac\n\n# Windows (from Windows or with MinGW cross-compiler)\nmake build-windows\n\n# Linux\ngo build -o tsc-bridge .\n```\n\n### Test\n\n```sh\ngo test ./...\n```\n\n### Full Release Build\n\nThe `build.sh` script builds all platforms, generates icons, creates the macOS\n`.app` bundle and DMG, and packages the Windows installer:\n\n```sh\n./build.sh\n```\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for\nguidelines. The most impactful way to contribute is by writing a driver for a\nprinter brand you have access to.\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmherrera53%2Flabelctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmherrera53%2Flabelctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmherrera53%2Flabelctl/lists"}