Skip to content

Commit 9fdb8d4

Browse files
steelbrainsteelbrain
committed
🆕 Initial commit
0 parents  commit 9fdb8d4

File tree

14 files changed

+2023
-0
lines changed

14 files changed

+2023
-0
lines changed

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
node_modules
2+
.DS_Store
3+
/bin
4+
/release
5+
6+
# Testing configs
7+
ffmpeg-over-ip.client.jsonc
8+
ffmpeg-over-ip.server.jsonc

‎LICENSE.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2025 @steelbrain
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.

‎Makefile‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
.PHONY: build clean install test cross-platform release
2+
3+
# Binary names
4+
CLIENT_BIN := ffmpeg-over-ip-client
5+
SERVER_BIN := ffmpeg-over-ip-server
6+
7+
# Binary output paths
8+
CLIENT_PATH := bin/$(CLIENT_BIN)
9+
SERVER_PATH := bin/$(SERVER_BIN)
10+
11+
# Go build flags
12+
GO_BUILD_FLAGS := -trimpath -ldflags="-s -w"
13+
14+
# Platforms to build for
15+
PLATFORMS := linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64
16+
17+
# Default target
18+
all: build
19+
20+
# Build both client and server
21+
build: $(CLIENT_PATH) $(SERVER_PATH)
22+
23+
# Build client binary
24+
$(CLIENT_PATH):
25+
@mkdir -p bin
26+
go build $(GO_BUILD_FLAGS) -o $(CLIENT_PATH) ./cmd/client
27+
28+
# Build server binary
29+
$(SERVER_PATH):
30+
@mkdir -p bin
31+
go build $(GO_BUILD_FLAGS) -o $(SERVER_PATH) ./cmd/server
32+
33+
# Clean build artifacts
34+
clean:
35+
rm -rf bin
36+
rm -rf release
37+
38+
# Install binaries to GOPATH/bin
39+
install: build
40+
go install $(GO_BUILD_FLAGS) ./cmd/client
41+
go install $(GO_BUILD_FLAGS) ./cmd/server
42+
43+
# Run tests
44+
test:
45+
go test -v ./...
46+
47+
# Format code
48+
fmt:
49+
go fmt ./...
50+
51+
# Run the server with test configuration
52+
run-server: $(SERVER_PATH)
53+
./$(SERVER_PATH) --config test-config/server.jsonc
54+
55+
# Run the client with test configuration
56+
run-client: $(CLIENT_PATH)
57+
./$(CLIENT_PATH) --config test-config/client.jsonc
58+
59+
# Cross-compile for all platforms
60+
cross-platform:
61+
@mkdir -p release
62+
@for platform in $(PLATFORMS); do \
63+
os="$${platform%%/*}"; \
64+
arch="$${platform#*/}"; \
65+
output_dir="release/$$os-$$arch"; \
66+
mkdir -p $$output_dir; \
67+
ext=""; \
68+
if [ "$$os" = "windows" ]; then ext=".exe"; fi; \
69+
echo "Building for $$os/$$arch..."; \
70+
GOOS=$$os GOARCH=$$arch go build $(GO_BUILD_FLAGS) -o $$output_dir/$(CLIENT_BIN)$$ext ./cmd/client; \
71+
GOOS=$$os GOARCH=$$arch go build $(GO_BUILD_FLAGS) -o $$output_dir/$(SERVER_BIN)$$ext ./cmd/server; \
72+
done
73+
74+
# Package the cross-compiled binaries
75+
release: cross-platform
76+
@mkdir -p release/archives
77+
@for platform in $(PLATFORMS); do \
78+
os="$${platform%%/*}"; \
79+
arch="$${platform#*/}"; \
80+
echo "Creating archive for $$os-$$arch..."; \
81+
tar -czf release/archives/ffmpeg-over-ip-$$os-$$arch.tar.gz -C release/$$os-$$arch .; \
82+
done
83+
@echo "Release archives created in release/archives/ directory"

‎README.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# ffmpeg-over-ip
2+
3+
[ffmpeg-over-ip][] is a client-server combo that allows you to transcode videos on a machine with access to a GPU from a container or a VM without having to passthrough a GPU. This means you can run GPU accelerated ffmpeg from a docker container and use the GPU from the hypervisor **or your Gaming PC running Windows**.
4+
5+
If you're looking for **v3** (pre Golang rewrite), please check out [v3 branch](https://github.com/steelbrain/ffmpeg-over-ip/tree/v3)
6+
7+
## How it works
8+
9+
ffmpeg-over-ip uses a shared filesystem (this could be a Docker mount, NFS or SMB) to transfer video data and a lightweight communication protocol to coordinate the commands. This means that you do not need an ssh server running on the GPU-host (making Windows support easier/simpler), and that the client can stream the output(s) as they are processed. This allows ffmpeg-over-ip to be used in [Plex][] or [Emby][] media servers for just-in-time transcoding.
10+
11+
## Key Features
12+
13+
- **Real-time Streaming**: Output(s) from ffmpeg processes are streamed in real-time to the client through filesystem
14+
- **Robust Cancellation**: Client can cancel running processes, and server properly cleans up resources
15+
- **Flexible Connectivity**: Supports both TCP and Unix socket connections
16+
- **Path and Command Rewrites**: Configure path or codec mappings to handle differences between client and server
17+
- **Authentication**: Client & Server communicate through HMAC signed messages
18+
19+
## Installation
20+
21+
### Option 1: Download Pre-built Binaries (Recommended)
22+
23+
Download the latest binaries for your platform from the [GitHub Releases](https://github.com/steelbrain/ffmpeg-over-ip/releases) page.
24+
25+
1. Navigate to the releases page and download the appropriate binaries for your platform
26+
2. Extract the archive to get the `ffmpeg-over-ip-client` and `ffmpeg-over-ip-server` executables
27+
3. Make the binaries executable if needed: `chmod +x ffmpeg-over-ip-*`
28+
29+
### Option 2: Build from Source
30+
31+
If you prefer to build from source:
32+
33+
1. Make sure you have Go 1.18+ installed
34+
2. Clone the repository: `git clone https://github.com/steelbrain/ffmpeg-over-ip.git`
35+
3. Use the included Makefile:
36+
37+
```bash
38+
# Build both client and server binaries
39+
make build
40+
41+
# Install to your Go path (optional)
42+
make install
43+
```
44+
45+
The built binaries will be placed in the `bin` directory as `ffmpeg-over-ip-client` and `ffmpeg-over-ip-server`.
46+
47+
## Configuration
48+
49+
Both the client and server are configured using JSONC (JSON with comments) configuration files. Example configuration files for both the server and client are included in the repository as `template.ffmpeg-over-ip-client.jsonc` and `template.ffmpeg-over-ip-server.jsonc`.
50+
51+
### Finding Configuration Paths
52+
53+
To see where the application looks for configuration files:
54+
55+
```bash
56+
# For the client
57+
./bin/ffmpeg-over-ip-client --debug-print-search-paths
58+
59+
# For the server
60+
./bin/ffmpeg-over-ip-server --debug-print-search-paths
61+
```
62+
63+
### Environment Variable Configuration
64+
65+
In addition to configuration files, you can also specify the configuration file path via environment variables:
66+
67+
```bash
68+
# For the client
69+
export FFMPEG_OVER_IP_CLIENT_CONFIG="/path/to/custom-client-config.jsonc"
70+
71+
# For the server
72+
export FFMPEG_OVER_IP_SERVER_CONFIG="/path/to/custom-server-config.jsonc"
73+
```
74+
75+
This is particularly useful in containerized environments or when you want to easily switch between different configuration files without modifying command-line arguments.
76+
77+
### Client Configuration
78+
79+
Create a client configuration file in one of the default search paths, or specify it with `--config`:
80+
81+
```jsonc
82+
{
83+
// Where logs should go. Can be "stdout", "stderr", a file path, or false/null to disable logging
84+
"log": "/tmp/ffmpeg-over-ip-client.log",
85+
86+
// Server address: "hostname:port" for TCP or "/path/to/socket" for Unix socket
87+
"address": "localhost:5050",
88+
89+
// Authentication secret (must match server config)
90+
"authSecret": "your-secret-here"
91+
}
92+
```
93+
94+
### Server Configuration
95+
96+
Create a server configuration file similarly:
97+
98+
```jsonc
99+
{
100+
// Where logs should go. Can be "stdout", "stderr", a file path, or false/null to disable logging
101+
"log": "stdout",
102+
103+
// Listen address: "hostname:port" for TCP or "/path/to/socket" for Unix socket
104+
"address": "0.0.0.0:5050",
105+
106+
// Authentication secret (must match client config)
107+
"authSecret": "your-secret-here",
108+
109+
// Path to ffmpeg binary on the server
110+
"ffmpegPath": "/usr/bin/ffmpeg",
111+
112+
// Path rewrites to map client paths to server paths
113+
"rewrites": [
114+
// File path rewrites - maps client paths to server paths
115+
["/client/path", "/server/path"],
116+
["/another/client/path", "/corresponding/server/path"],
117+
118+
// Codec rewrites - allow transparent use of hardware-accelerated codecs
119+
["h264_nvenc", "h264_qsv"], // Use Intel QuickSync instead of NVIDIA for h264
120+
["hevc_nvenc", "hevc_vaapi"], // Use VAAPI instead of NVIDIA for HEVC
121+
["cuda", "qsv"] // Use QuickSync acceleration instead of CUDA
122+
]
123+
}
124+
```
125+
126+
## Usage
127+
128+
### Starting the Server
129+
130+
```bash
131+
# Uses default configuration paths
132+
./bin/ffmpeg-over-ip-server
133+
134+
# Uses the specified configuration path
135+
./bin/ffmpeg-over-ip-server --config /path/to/your/server-config.jsonc
136+
137+
# Uses configuration path from environment variable
138+
FFMPEG_OVER_IP_SERVER_CONFIG="/path/to/your/server-config.jsonc" ./bin/ffmpeg-over-ip-server
139+
```
140+
141+
### Using the Client
142+
143+
Use the client exactly as you would use ffmpeg, with the same arguments:
144+
145+
```bash
146+
# Uses default configuration paths
147+
./bin/ffmpeg-over-ip-client -i input.mp4 -c:v libx264 -preset medium output.mp4
148+
149+
# Uses the specified configuration path
150+
./bin/ffmpeg-over-ip-client --config /path/to/your/client-config.jsonc -i input.mp4 output.mp4
151+
152+
# Uses configuration path from environment variable
153+
FFMPEG_OVER_IP_CLIENT_CONFIG="/path/to/your/client-config.jsonc" ./bin/ffmpeg-over-ip-client -i input.mp4 output.mp4
154+
```
155+
156+
## Docker Integration
157+
158+
You can use ffmpeg-over-ip in Docker environments by mounting the client binary:
159+
160+
```bash
161+
docker run -v ./path/to/ffmpeg-over-ip-client:/usr/bin/ffmpeg \
162+
-v ./path/to/config:/etc/ffmpeg-over-ip.client.jsonc \
163+
your-image
164+
```
165+
166+
This allows containers to use ffmpeg remotely without needing GPU passthrough or other special setup.
167+
168+
## Development
169+
170+
### Project Structure
171+
172+
- `cmd/client`: Client implementation
173+
- `cmd/server`: Server implementation
174+
- `pkg/common`: Shared utilities
175+
- `pkg/config`: Configuration handling
176+
- `pkg/protocol`: Network protocol implementation
177+
178+
### Environment Variables
179+
180+
For security reasons, only a limited set of environment variables are allowed for expansion in log paths:
181+
- HOME, TMPDIR, TMP, TEMP, USER, LOGDIR, PWD, XDG_*
182+
183+
## License
184+
185+
The contents of this project are licensed under the terms of the MIT License.
186+
187+
[ffmpeg-over-ip]: https://ffmpeg-over-ip.com
188+
[Plex]: https://www.plex.tv/
189+
[Emby]: https://www.emby.media/

0 commit comments

Comments
 (0)