Building Server Binary

The Raffi streaming server is a Go application that handles HLS transcoding, torrent streaming, and media delivery. It’s compiled into platform-specific binaries and bundled with the desktop app.

Overview

The server provides:

HLS Transcoding: Converts video streams to HTTP Live Streaming format
Torrent Streaming: Streams content directly from torrent/magnet links
Media Probing: Analyzes video files for metadata and codec information
Session Management: Handles multiple concurrent streaming sessions
Chromecast Support: Streaming to Chromecast devices

Prerequisites

Go 1.25+ (specified in go.mod)
CGO: Required for SQLite support
C Compiler:
- Windows: GCC (via MinGW or TDM-GCC)
- macOS: Xcode Command Line Tools
- Linux: GCC (usually pre-installed)

Project Structure

raffi-server/
├── main.go                    # Entry point and HTTP server
├── cast.go                    # Chromecast functionality
├── clip.go                    # Video clipping
├── community_addons.go        # Stremio addon integration
├── go.mod                     # Go module definition
├── go.sum                     # Dependency checksums
└── src/
    ├── session/               # Session management
    │   └── session.go
    └── stream/                # Streaming logic
        ├── torrent.go         # Torrent client
        └── hls/               # HLS transcoding
            ├── controller.go
            ├── lifecycle.go
            ├── monitor.go
            ├── playlist.go
            ├── probe.go
            ├── session.go
            ├── transcoder.go
            ├── throttle_unix.go
            └── throttle_windows.go

Dependencies

Key dependencies from go.mod:

module raffi-server

go 1.25

require (
    github.com/anacrolix/torrent v1.59.1  // Torrent client
    github.com/gorilla/websocket v1.5.0   // WebSocket support
    zombiezen.com/go/sqlite v0.13.1       // SQLite database
    golang.org/x/sys v0.34.0              // System calls
    // ... and more
)

Building Standalone

Basic Build

To build the server binary directly:

Navigate to server directory

cd raffi-server

Build the binary

go build -o decoder .

This creates a decoder binary for your current platform.

Run the server

./decoder

The server starts on http://localhost:8080 by default.

Optimized Build

For smaller binary size and better performance:

go build -ldflags="-s -w" -tags=sqlite_omit_load_extension -o decoder .

Build Flags:

-ldflags="-s -w": Strip debug info and symbol table
-tags=sqlite_omit_load_extension: Disable SQLite extension loading
-o decoder: Output filename

Platform-Specific Builds

The desktop app uses raffi-desktop/build_binary.cjs to compile platform-specific binaries.

Windows Build

CGO_ENABLED=1 \
CC=gcc \
go build \
  -ldflags="-s -w -extldflags '-static'" \
  -tags=sqlite_omit_load_extension \
  -o decoder-windows-amd64.exe \
  .

Output: decoder-windows-amd64.exe Requirements:

GCC compiler (MinGW-w64 or TDM-GCC)
Static linking for portability

Linux Build

CGO_ENABLED=1 \
go build \
  -ldflags="-s -w -extldflags '-static'" \
  -tags=sqlite_omit_load_extension \
  -o decoder-x86_64-unknown-linux-gnu \
  .

Output: decoder-x86_64-unknown-linux-gnu Requirements:

GCC compiler
Static linking for compatibility across distributions

macOS Build (ARM64)

CGO_ENABLED=1 \
GOARCH=arm64 \
go build \
  -ldflags="-s -w" \
  -tags=sqlite_omit_load_extension \
  -o decoder-aarch64-apple-darwin \
  .

Output: decoder-aarch64-apple-darwin Architecture: Apple Silicon (M1/M2/M3)

macOS Build (x64)

CGO_ENABLED=1 \
GOARCH=amd64 \
go build \
  -ldflags="-s -w" \
  -tags=sqlite_omit_load_extension \
  -o decoder-x86_64-apple-darwin \
  .

Output: decoder-x86_64-apple-darwin Architecture: Intel-based Macs

Cross-Compilation

To build for different platforms from a single machine:

Set target OS and architecture

export GOOS=linux
export GOARCH=amd64

Valid combinations:

GOOS=windows GOARCH=amd64
GOOS=linux GOARCH=amd64
GOOS=darwin GOARCH=amd64
GOOS=darwin GOARCH=arm64

Install cross-compilation tools

For cross-compiling with CGO, you need platform-specific C compilers:

# For Windows targets
sudo apt-get install gcc-mingw-w64

# For ARM targets
sudo apt-get install gcc-aarch64-linux-gnu

Build with appropriate C compiler

CGO_ENABLED=1 \
CC=x86_64-w64-mingw32-gcc \
GOOS=windows \
GOARCH=amd64 \
go build -o decoder-windows-amd64.exe .

Building from Desktop App

The desktop app automatically builds the server binary:

Navigate to desktop directory

cd raffi-desktop

Run the server build script

npm run server:build

This executes build_binary.cjs which:

Detects your current platform
Compiles the Go server with appropriate flags
Outputs to raffi-desktop/electron/decoder-{platform}

Build complete desktop app

npm run dist

This runs server:build, then builds the Electron app with the bundled binary.

Build Output Locations

When building from the desktop app, binaries are placed in:

raffi-desktop/electron/
├── decoder-windows-amd64.exe           # Windows binary
├── decoder-x86_64-unknown-linux-gnu    # Linux binary
├── decoder-aarch64-apple-darwin        # macOS ARM64 binary
└── decoder-x86_64-apple-darwin         # macOS Intel binary

These binaries are included in the Electron app as extraResources during packaging.

Binary Size Optimization

The build process optimizes binary size:

Flag	Purpose	Size Reduction
`-ldflags="-s"`	Strip debug info	~30%
`-ldflags="-w"`	Strip symbol table	~10%
`-tags=sqlite_omit_load_extension`	Remove SQLite extensions	~5%
`-extldflags '-static'`	Static linking	Varies

Typical binary sizes:

Windows: ~45 MB
Linux: ~40 MB
macOS: ~42 MB

Testing the Server

After building, test the server independently:

Run the binary

./decoder

Check the health endpoint

curl http://localhost:8080/health

Expected response:

{"status": "ok"}

Test streaming endpoint

curl http://localhost:8080/stream/{session-id}/playlist.m3u8

Environment Variables

The server supports configuration via environment variables:

# Server port (default: 8080)
export PORT=8080

# Torrent data directory
export TORRENT_DIR=/tmp/raffi-torrents

# Enable debug logging
export DEBUG=true

Deployment

Desktop App Bundle

The server binary is automatically bundled with the desktop app and managed by Electron:

Windows: resources/decoder-windows-amd64.exe
Linux: resources/decoder-x86_64-unknown-linux-gnu
macOS: resources/decoder-{arch}-apple-darwin

The Electron app spawns the server process on startup.

Standalone Server

For running the server independently (e.g., for mobile clients):

# Build optimized binary
go build -ldflags="-s -w" -o raffi-server .

# Run on custom port
PORT=9000 ./raffi-server

Mobile Integration

The mobile app connects to the server for torrent streaming:

Desktop app runs server on local network
Mobile app connects via http://{desktop-ip}:8080
Server handles transcoding and streaming

Troubleshooting

CGO Errors

If you encounter CGO-related build errors:

# Verify CGO is enabled
go env CGO_ENABLED

# Ensure C compiler is available
gcc --version

# Set CGO explicitly
export CGO_ENABLED=1

Static Linking Issues

On Linux, static linking may require additional libraries:

sudo apt-get install musl-dev

# Or use dynamic linking
go build -ldflags="-s -w" -o decoder .

Missing Dependencies

If build fails due to missing modules:

# Download all dependencies
go mod download

# Verify dependencies
go mod verify

# Tidy up go.mod and go.sum
go mod tidy

Advanced Builds

Debug Build

For debugging with symbol information:

go build -gcflags="all=-N -l" -o decoder-debug .

Race Detection

For detecting race conditions during development:

go build -race -o decoder-race .
./decoder-race

Profile-Guided Optimization

For maximum performance:

# Build with PGO
go build -pgo=auto -o decoder .

Getting Started

Architecture

Building

Contributing

Building Server Binary

Overview

Prerequisites

Project Structure

Dependencies

Building Standalone

Basic Build

Optimized Build

Platform-Specific Builds

Windows Build

Linux Build

macOS Build (ARM64)

macOS Build (x64)

Cross-Compilation

Building from Desktop App

Build Output Locations

Binary Size Optimization

Testing the Server

Environment Variables

Deployment

Desktop App Bundle

Standalone Server

Mobile Integration

Troubleshooting

CGO Errors

Static Linking Issues

Missing Dependencies

Advanced Builds

Debug Build

Race Detection

Profile-Guided Optimization

Build docs developers (and LLMs) love

Getting Started

Architecture

Building

Contributing

​Overview

​Prerequisites

​Project Structure

​Dependencies

​Building Standalone

​Basic Build

​Optimized Build

​Platform-Specific Builds

​Windows Build

​Linux Build

​macOS Build (ARM64)

​macOS Build (x64)

​Cross-Compilation

​Building from Desktop App

​Build Output Locations

​Binary Size Optimization

​Testing the Server

​Environment Variables

​Deployment

​Desktop App Bundle

​Standalone Server

​Mobile Integration

​Troubleshooting

​CGO Errors

​Static Linking Issues

​Missing Dependencies

​Advanced Builds

​Debug Build

​Race Detection

​Profile-Guided Optimization

Build docs developers (and LLMs) love

Overview

Prerequisites

Project Structure

Dependencies

Building Standalone

Basic Build

Optimized Build

Platform-Specific Builds

Windows Build

Linux Build

macOS Build (ARM64)

macOS Build (x64)

Cross-Compilation

Building from Desktop App

Build Output Locations

Binary Size Optimization

Testing the Server

Environment Variables

Deployment

Desktop App Bundle

Standalone Server

Mobile Integration

Troubleshooting

CGO Errors

Static Linking Issues

Missing Dependencies

Advanced Builds

Debug Build

Race Detection

Profile-Guided Optimization