From d01b99d1050270d8534421c1b2fbb314da8b27e1 Mon Sep 17 00:00:00 2001 From: Alex X Date: Fri, 6 Feb 2026 20:43:50 +0300 Subject: [PATCH] BIG docs refactoring --- .github/workflows/gh-pages.yml | 21 +- .gitignore | 4 +- .vitepress/config.mts | 177 --- .vitepress/theme/custom.css | 4 - .vitepress/theme/index.ts | 5 - README.md | 1663 ++++++------------------- api/README.md | 117 -- assets/codecs.svg | 4 - docker/README.md | 4 + internal/README.md | 67 + internal/alsa/README.md | 12 + internal/api/README.md | 47 +- internal/api/ws/README.md | 69 + internal/app/README.md | 43 +- internal/bubble/README.md | 15 + internal/debug/README.md | 3 + internal/doorbird/README.md | 2 +- internal/dvrip/README.md | 21 + internal/echo/README.md | 48 + internal/eseecloud/README.md | 12 + internal/exec/README.md | 36 + internal/expr/README.md | 2 + internal/ffmpeg/README.md | 112 +- internal/ffmpeg/device/README.md | 22 + internal/flussonic/README.md | 5 + internal/gopro/README.md | 6 +- internal/hass/README.md | 41 + internal/hls/README.md | 16 + internal/homekit/README.md | 97 ++ internal/http/README.md | 47 + internal/isapi/README.md | 14 + internal/ivideon/README.md | 10 + internal/mjpeg/README.md | 50 +- internal/mp4/README.md | 66 + internal/mpegts/README.md | 28 + internal/multitrans/README.md | 12 +- internal/nest/README.md | 11 + internal/ngrok/README.md | 2 + internal/onvif/README.md | 17 + internal/ring/README.md | 17 + internal/roborock/README.md | 15 + internal/rtmp/README.md | 58 + internal/rtsp/README.md | 93 ++ internal/srtp/README.md | 13 + internal/streams/README.md | 86 ++ internal/tapo/README.md | 61 + internal/tuya/README.md | 4 +- internal/v4l2/README.md | 4 +- internal/webrtc/README.md | 159 ++- internal/webtorrent/README.md | 45 + internal/wyoming/README.md | 3 + internal/wyze/README.md | 78 +- internal/xiaomi/README.md | 4 +- internal/yandex/README.md | 2 +- package.json | 18 +- pkg/ffmpeg/README.md | 68 + scripts/README.md | 46 +- website/.vitepress/config.js | 147 +++ website/README.md | 9 + website/api/index.html | 4 +- {api => website/api}/openapi.yaml | 0 website/favicon.ico | Bin 0 -> 15086 bytes {assets => website/images}/go2rtc.png | Bin {assets => website/images}/logo.gif | Bin {assets => website/images}/logo.png | Bin website/index.html | 28 - www/README.md | 126 +- 67 files changed, 2104 insertions(+), 1916 deletions(-) delete mode 100644 .vitepress/config.mts delete mode 100644 .vitepress/theme/custom.css delete mode 100644 .vitepress/theme/index.ts delete mode 100644 api/README.md delete mode 100644 assets/codecs.svg create mode 100644 internal/README.md create mode 100644 internal/alsa/README.md create mode 100644 internal/api/ws/README.md create mode 100644 internal/bubble/README.md create mode 100644 internal/debug/README.md create mode 100644 internal/dvrip/README.md create mode 100644 internal/echo/README.md create mode 100644 internal/eseecloud/README.md create mode 100644 internal/ffmpeg/device/README.md create mode 100644 internal/flussonic/README.md create mode 100644 internal/hass/README.md create mode 100644 internal/homekit/README.md create mode 100644 internal/http/README.md create mode 100644 internal/isapi/README.md create mode 100644 internal/ivideon/README.md create mode 100644 internal/mp4/README.md create mode 100644 internal/mpegts/README.md create mode 100644 internal/nest/README.md create mode 100644 internal/ring/README.md create mode 100644 internal/roborock/README.md create mode 100644 internal/rtsp/README.md create mode 100644 internal/srtp/README.md create mode 100644 internal/tapo/README.md create mode 100644 internal/webtorrent/README.md create mode 100644 pkg/ffmpeg/README.md create mode 100644 website/.vitepress/config.js create mode 100644 website/README.md rename {api => website/api}/openapi.yaml (100%) create mode 100644 website/favicon.ico rename {assets => website/images}/go2rtc.png (100%) rename {assets => website/images}/logo.gif (100%) rename {assets => website/images}/logo.png (100%) delete mode 100644 website/index.html diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 9950a1c8..65005306 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -2,9 +2,7 @@ name: Deploy static content to Pages on: - push: - branches: - - master + # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages @@ -16,7 +14,7 @@ permissions: # Allow one concurrent deployment concurrency: group: "pages" - cancel-in-progress: false + cancel-in-progress: true jobs: build: @@ -24,8 +22,6 @@ jobs: steps: - name: Checkout uses: actions/checkout@v5 - with: - fetch-depth: 0 - name: Setup Node uses: actions/setup-node@v6 with: @@ -36,27 +32,22 @@ jobs: - name: Build docs run: npm run docs:build - name: Copy docs into website - run: rsync -a --exclude 'api/' .vitepress/dist/ website/ + run: rsync -a --exclude '.vitepress/' --exclude 'README.md' website/ website/.vitepress/dist/ - name: Setup Pages uses: actions/configure-pages@v5 - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: - path: './website' + path: website/.vitepress/dist + # Single deploy job since we're just deploying deploy: - needs: build - - permissions: - pages: write - id-token: write - environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest + needs: build steps: - - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index de784c79..331ef53d 100644 --- a/.gitignore +++ b/.gitignore @@ -16,8 +16,8 @@ go2rtc_win* .DS_Store -.vitepress/cache -.vitepress/dist +website/.vitepress/cache +website/.vitepress/dist node_modules package-lock.json \ No newline at end of file diff --git a/.vitepress/config.mts b/.vitepress/config.mts deleted file mode 100644 index 874118c6..00000000 --- a/.vitepress/config.mts +++ /dev/null @@ -1,177 +0,0 @@ -import fs from 'fs'; -import path from 'path'; -import { defineConfig } from 'vitepress'; - -const repoRoot = path.resolve(__dirname, '..'); -const srcDir = repoRoot; -const skipDirs = new Set(['.git', 'node_modules', '.vitepress', 'dist', 'scripts']); - -function walkForReadmes(dir: string, results: string[]) { - for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { - if (entry.isDirectory()) { - if (skipDirs.has(entry.name)) { - continue; - } - walkForReadmes(path.join(dir, entry.name), results); - continue; - } - - if (entry.isFile() && entry.name === 'README.md') { - results.push(path.join(dir, entry.name)); - } - } -} - -function extractTitle(filePath: string) { - const content = fs.readFileSync(filePath, 'utf8'); - let inFence = false; - - for (const line of content.split(/\r?\n/)) { - if (/^(```|~~~)/.test(line)) { - inFence = !inFence; - continue; - } - - if (inFence) { - continue; - } - - const match = line.match(/^#\s+(.+)$/); - if (match) { - return match[1].trim(); - } - } - - return ''; -} - -function toTitleCase(value: string) { - return value - .replace(/[-_]/g, ' ') - .replace(/\b\w/g, (char) => char.toUpperCase()); -} - -function toLink(routePath: string) { - const clean = routePath.replace(/index\.md$/, ''); - return clean ? `/${clean}` : '/'; -} - -const readmeFiles: string[] = []; -walkForReadmes(srcDir, readmeFiles); - -const readmePaths = readmeFiles - .map((filePath) => path.relative(srcDir, filePath).replace(/\\/g, '/')) - .sort(); - -const rewrites = Object.fromEntries( - readmePaths.map((relPath) => [relPath, relPath.replace(/README\.md$/, 'index.md')]) -); - -const groupOrder = ['', 'docker', 'api', 'pkg', 'internal', 'examples', 'www']; -const groupTitles = new Map([ - ['', 'Overview'], - ['api', 'API'], - ['pkg', 'Packages'], - ['internal', 'Internal'], - ['examples', 'Examples'], - ['docker', 'Docker'], - ['www', 'WWW'], -]); - -const groupedItems = new Map>(); - -for (const relPath of readmePaths) { - const filePath = path.join(srcDir, relPath); - const segments = relPath.split('/'); - const groupKey = segments.length > 1 ? segments[0] : ''; - const routePath = rewrites[relPath]; - const link = toLink(routePath); - const title = extractTitle(filePath); - const fallback = segments.length > 1 ? segments[segments.length - 2] : 'Overview'; - const text = title || toTitleCase(fallback); - - if (!groupedItems.has(groupKey)) { - groupedItems.set(groupKey, []); - } - groupedItems.get(groupKey)?.push({ text, link }); -} - -for (const items of groupedItems.values()) { - items.sort((a, b) => a.text.localeCompare(b.text)); -} - -const orderedGroups = [...groupedItems.entries()].sort((a, b) => { - const indexA = groupOrder.indexOf(a[0]); - const indexB = groupOrder.indexOf(b[0]); - if (indexA !== -1 || indexB !== -1) { - return (indexA === -1 ? Number.POSITIVE_INFINITY : indexA) - - (indexB === -1 ? Number.POSITIVE_INFINITY : indexB); - } - return a[0].localeCompare(b[0]); -}); - -const sidebar = orderedGroups.flatMap(([groupKey, items]) => { - const groupTitle = groupTitles.get(groupKey) || toTitleCase(groupKey || 'Overview'); - if (items.length === 1) { - const [item] = items; - return [{ text: groupTitle, link: item.link }]; - } - return [{ - text: groupTitle, - collapsed: groupKey !== '', - items, - }]; -}); - -const nav = orderedGroups - .filter(([, items]) => items.length > 0) - .map(([groupKey, items]) => { - if (groupKey === '') { - return { text: groupTitles.get(groupKey) || 'Overview', link: '/' }; - } - const landing = items.find((item) => item.link === `/${groupKey}/`) ?? items[0]; - return { - text: groupTitles.get(groupKey) || toTitleCase(groupKey), - link: landing.link, - }; - }); - -export default defineConfig({ - lang: 'en-US', - title: 'go2rtc Docs', - description: 'go2rtc documentation', - srcDir, - base: process.env.BASE_URL || '/', - cleanUrls: true, - ignoreDeadLinks: true, - rewrites, - head: [ - ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }], - ['link', { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }], - [ - 'link', - { - rel: 'stylesheet', - href: - 'https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap', - }, - ], - ], - markdown: { - theme: { - light: "catppuccin-latte", - dark: "catppuccin-mocha", - }, - }, - themeConfig: { - nav, - sidebar: { - '/': sidebar, - }, - outline: [2, 3], - search: { - provider: 'local', - }, - socialLinks: [{ icon: "github", link: "https://github.com/AlexxIT/go2rtc" }], - }, -}); diff --git a/.vitepress/theme/custom.css b/.vitepress/theme/custom.css deleted file mode 100644 index 1a501f75..00000000 --- a/.vitepress/theme/custom.css +++ /dev/null @@ -1,4 +0,0 @@ - -.VPSidebarItem.level-1 { - font-weight: 700; -} \ No newline at end of file diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts deleted file mode 100644 index b4754c50..00000000 --- a/.vitepress/theme/index.ts +++ /dev/null @@ -1,5 +0,0 @@ -import DefaultTheme from 'vitepress/theme'; -import "@catppuccin/vitepress/theme/mocha/mauve.css"; -import './custom.css'; - -export default DefaultTheme; diff --git a/README.md b/README.md index 5366f8be..864d6aa7 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,41 @@

- - ![go2rtc](assets/logo.gif) -
- [![stars](https://img.shields.io/github/stars/AlexxIT/go2rtc?style=flat-square&logo=github)](https://github.com/AlexxIT/go2rtc/stargazers) - [![docker pulls](https://img.shields.io/docker/pulls/alexxit/go2rtc?style=flat-square&logo=docker&logoColor=white&label=pulls)](https://hub.docker.com/r/alexxit/go2rtc) - [![releases](https://img.shields.io/github/downloads/AlexxIT/go2rtc/total?color=blue&style=flat-square&logo=github)](https://github.com/AlexxIT/go2rtc/releases) - [![goreport](https://goreportcard.com/badge/github.com/AlexxIT/go2rtc)](https://goreportcard.com/report/github.com/AlexxIT/go2rtc) + + go2rtc - GitHub +

+

+ + go2rtc - GitHub Stars + + + go2rtc - Docker Pulls + + + go2rtc - GitHub Downloads + +

+

+ + go2rtc - Trendshift + +

-Ultimate camera streaming application with support for RTSP, WebRTC, HomeKit, FFmpeg, RTMP, etc. +Ultimate camera streaming application with support for dozens formats and protocols. -![go2rtc overview](assets/go2rtc.png) +- zero-dependency [small app](#go2rtc-binary) for all OS (Windows, macOS, Linux, FreeBSD) +- zero-delay for many [supported protocols](#codecs-madness) (lowest possible streaming latency) +- [streaming input](#streaming-input) from dozens formats and protocols +- [streaming output](#streaming-output) in all popular formats +- [streaming ingest](#streaming-ingest) in a number of popular formats +- [publish](#publish-stream) any source to popular streaming services (YouTube, Telegram) +- on-the-fly transcoding only if necessary via [FFmpeg](internal/ffmpeg/README.md) +- [two-way audio](#two-way-audio) support for many formats +- [streaming audio](#stream-to-camera) to all cameras with [two-way audio](#two-way-audio) support +- mixing tracks from different sources to single stream +- [auto-match](www/README.md#javascript-api) client-supported streaming formats and codecs +- can be [integrated to any project](#projects-using-go2rtc) or be used as [standalone app](#go2rtc-binary) -- zero-dependency and zero-config [small app](#go2rtc-binary) for all OS (Windows, macOS, Linux, ARM) -- zero-delay for many supported protocols (lowest possible streaming latency) -- streaming from [RTSP](#source-rtsp), [RTMP](#source-rtmp), [DVRIP](#source-dvrip), [HTTP](#source-http) (FLV/MJPEG/JPEG/TS), [USB Cameras](#source-ffmpeg-device) and [other sources](#module-streams) -- streaming from any sources, supported by [FFmpeg](#source-ffmpeg) -- streaming to [RTSP](#module-rtsp), [WebRTC](#module-webrtc), [MSE/MP4](#module-mp4), [HomeKit](#module-homekit) [HLS](#module-hls) or [MJPEG](#module-mjpeg) -- [publish](#publish-stream) any source to popular streaming services (YouTube, Telegram, etc.) -- first project in the World with support streaming from [HomeKit Cameras](#source-homekit) -- on-the-fly transcoding for unsupported codecs via [FFmpeg](#source-ffmpeg) -- play audio files and live streams on some cameras with [speaker](#stream-to-camera) -- multi-source two-way [codecs negotiation](#codecs-negotiation) - - mixing tracks from different sources to single stream - - auto-match client-supported codecs - - [two-way audio](#two-way-audio) for some cameras -- can be [integrated to](#module-api) any smart home platform or be used as [standalone app](#go2rtc-binary) - -**Supported Formats** - describes the communication API: authorization, encryption, command set, structure of media packets - -- devices: `alsa` (Linux audio), `v4l2` (Linux video) -- files: `adts`, `flv`, `h264`, `hevc`, `hls`, `mjpeg`, `mpegts`, `mp4`, `wav` -- network (public and well known): `mpjpeg`, `onvif`, `rtmp`, `rtp`, `rtsp`, `webrtc`, `yuv4mpegpipe` -- network (private and exclusive): `bubble`, `doorbird`, `dvrip`, `eseecloud`, `gopro`, `hass` (Home Assistant), `homekit` (Apple), `isapi` (Hikvision), `kasa` (TP-Link), `multitrans` (TP-Link), `nest` (Google), `ring`, `roborock`, `tapo` and `vigi` (TP-Link), `tuya`, `webtorrent`, `wyze`, `xiaomi` (Mi Home) -- webrtc related: `creality`, `kinesis` (Amazon), `openipc`, `switchbot`, `whep`, `whip`, `wyze` -- other: `ascii`, `echo`, `exec`, `expr`, `ffmpeg` - -**Supported Protocols** - describes the transport for data transmission - -- public: `http`, `pipe`, `rtmp`, `rtsp`, `tcp`, `udp`, `webrtc`, `ws` (WebSocket) -- private: `cs2` (PPPP), `hap` and `hds` (HomeKit), `tutk` (P2P) - -**Inspired by:** +#### Inspired by - series of streaming projects from [@deepch](https://github.com/deepch) - [webrtc](https://github.com/pion/webrtc) go library and whole [@pion](https://github.com/pion) team @@ -51,1213 +45,392 @@ Ultimate camera streaming application with support for RTSP, WebRTC, HomeKit, FF - HomeKit Accessory Protocol from [@brutella](https://github.com/brutella/hap) - creator of the project's logo [@v_novoseltsev](https://www.instagram.com/v_novoseltsev) -> [!CAUTION] -> The official website of the project is this GitHub repository and go2rtc.org (hosted on GitHub Pages). The website go2rtc[.]com is in no way associated with the authors of this project. +
+
+Table of Contents ---- - -- [Fast start](#fast-start) +- [Installation](#installation) - [go2rtc: Binary](#go2rtc-binary) - [go2rtc: Docker](#go2rtc-docker) - [go2rtc: Home Assistant add-on](#go2rtc-home-assistant-add-on) - - [go2rtc: Home Assistant integration](#go2rtc-home-assistant-integration) - - [go2rtc: Dev version](#go2rtc-dev-version) + - [go2rtc: Home Assistant Integration](#go2rtc-home-assistant-integration) + - [go2rtc: Master version](#go2rtc-master-version) - [Configuration](#configuration) - - [Module: Streams](#module-streams) +- [Features](#features) + - [Streaming input](#streaming-input) + - [Streaming output](#streaming-output) + - [Streaming ingest](#streaming-ingest) - [Two-way audio](#two-way-audio) - - [Source: RTSP](#source-rtsp) - - [Source: RTMP](#source-rtmp) - - [Source: HTTP](#source-http) - - [Source: ONVIF](#source-onvif) - - [Source: FFmpeg](#source-ffmpeg) - - [Source: FFmpeg Device](#source-ffmpeg-device) - - [Source: Exec](#source-exec) - - [Source: Echo](#source-echo) - - [Source: Expr](#source-expr) - - [Source: HomeKit](#source-homekit) - - [Source: Bubble](#source-bubble) - - [Source: DVRIP](#source-dvrip) - - [Source: Tapo](#source-tapo) - - [Source: Kasa](#source-kasa) - - [Source: Multitrans](#source-multitrans) - - [Source: Tuya](#source-tuya) - - [Source: Xiaomi](#source-xiaomi) - - [Source: Wyze](#source-wyze) - - [Source: GoPro](#source-gopro) - - [Source: Ivideon](#source-ivideon) - - [Source: Hass](#source-hass) - - [Source: ISAPI](#source-isapi) - - [Source: Nest](#source-nest) - - [Source: Ring](#source-ring) - - [Source: Roborock](#source-roborock) - - [Source: Doorbird](#source-doorbird) - - [Source: WebRTC](#source-webrtc) - - [Source: WebTorrent](#source-webtorrent) - - [Incoming sources](#incoming-sources) - [Stream to camera](#stream-to-camera) - [Publish stream](#publish-stream) - [Preload stream](#preload-stream) - - [Module: API](#module-api) - - [Module: RTSP](#module-rtsp) - - [Module: RTMP](#module-rtmp) - - [Module: WebRTC](#module-webrtc) - - [Module: HomeKit](#module-homekit) - - [Module: WebTorrent](#module-webtorrent) - - [Module: ngrok](#module-ngrok) - - [Module: Hass](#module-hass) - - [Module: MP4](#module-mp4) - - [Module: HLS](#module-hls) - - [Module: MJPEG](#module-mjpeg) - - [Module: Log](#module-log) +- [Codecs](#codecs) + - [Codecs filters](#codecs-filters) + - [Codecs madness](#codecs-madness) + - [Built-in transcoding](#built-in-transcoding) + - [Codecs negotiation](#codecs-negotiation) - [Security](#security) -- [Codecs filters](#codecs-filters) -- [Codecs madness](#codecs-madness) -- [Codecs negotiation](#codecs-negotiation) - [Projects using go2rtc](#projects-using-go2rtc) - [Camera experience](#camera-experience) - [Tips](#tips) -# Fast start +
-1. Download [binary](#go2rtc-binary) or use [Docker](#go2rtc-docker) or Home Assistant [add-on](#go2rtc-home-assistant-add-on) or [Integration](#go2rtc-home-assistant-integration) +## Installation + +1. Download [binary](#go2rtc-binary) or use [Docker](#go2rtc-docker) or Home Assistant [add-on](#go2rtc-home-assistant-add-on) or [integration](#go2rtc-home-assistant-integration) 2. Open web interface: `http://localhost:1984/` - -**Optionally:** - -- add your [streams](#module-streams) to [config](#configuration) file -- setup [external access](#module-webrtc) to webrtc +3. Add [streams](#streaming-input) to [config](#configuration) **Developers:** -- write your own [web interface](#module-api) -- integrate [web api](#module-api) into your smart home platform +- integrate [HTTP API](internal/api/README.md) into your smart home platform -## go2rtc: Binary +### go2rtc: Binary Download binary for your OS from [latest release](https://github.com/AlexxIT/go2rtc/releases/): -- `go2rtc_win64.zip` - Windows 10+ 64-bit -- `go2rtc_win32.zip` - Windows 10+ 32-bit -- `go2rtc_win_arm64.zip` - Windows ARM 64-bit -- `go2rtc_linux_amd64` - Linux 64-bit -- `go2rtc_linux_i386` - Linux 32-bit -- `go2rtc_linux_arm64` - Linux ARM 64-bit (ex. Raspberry 64-bit OS) -- `go2rtc_linux_arm` - Linux ARM 32-bit (ex. Raspberry 32-bit OS) -- `go2rtc_linux_armv6` - Linux ARMv6 (for old Raspberry 1 and Zero) -- `go2rtc_linux_mipsel` - Linux MIPS (ex. [Xiaomi Gateway 3](https://github.com/AlexxIT/XiaomiGateway3), [Wyze cameras](https://github.com/gtxaspec/wz_mini_hacks)) -- `go2rtc_mac_amd64.zip` - macOS 11+ Intel 64-bit -- `go2rtc_mac_arm64.zip` - macOS ARM 64-bit -- `go2rtc_freebsd_amd64.zip` - FreeBSD 64-bit -- `go2rtc_freebsd_arm64.zip` - FreeBSD ARM 64-bit +| name | description | +|-----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| +| [go2rtc_win64.zip](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_win64.zip) | Windows 10+ 64-bit | +| [go2rtc_win32.zip](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_win32.zip) | Windows 10+ 32-bit | +| [go2rtc_win_arm64.zip](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_win_arm64.zip) | Windows ARM 64-bit | +| [go2rtc_linux_amd64](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_linux_amd64) | Linux 64-bit | +| [go2rtc_linux_i386](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_linux_i386) | Linux 32-bit | +| [go2rtc_linux_arm64](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_linux_arm64) | Linux ARM 64-bit (ex. Raspberry 64-bit OS) | +| [go2rtc_linux_arm](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_linux_arm) | Linux ARM 32-bit (ex. Raspberry 32-bit OS) | +| [go2rtc_linux_armv6](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_linux_armv6) | Linux ARMv6 (for old Raspberry 1 and Zero) | +| [go2rtc_linux_mipsel](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_linux_mipsel) | Linux MIPS (ex. [Xiaomi Gateway 3](https://github.com/AlexxIT/XiaomiGateway3), [Wyze cameras](https://github.com/gtxaspec/wz_mini_hacks)) | +| [go2rtc_mac_amd64.zip](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_mac_amd64.zip) | macOS 11+ Intel 64-bit | +| [go2rtc_mac_arm64.zip](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_mac_arm64.zip) | macOS ARM 64-bit | +| [go2rtc_freebsd_amd64.zip](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_freebsd_amd64.zip) | FreeBSD 64-bit | +| [go2rtc_freebsd_arm64.zip](https://github.com/AlexxIT/go2rtc/releases/latest/download/go2rtc_freebsd_arm64.zip) | FreeBSD ARM 64-bit | Don't forget to fix the rights `chmod +x go2rtc_xxx_xxx` on Linux and Mac. PS. The application is compiled with the latest versions of the Go language for maximum speed and security. Therefore, the [minimum OS versions](https://go.dev/wiki/MinimumRequirements) depend on the Go language. -## go2rtc: Docker +### go2rtc: Docker -The Docker container [`alexxit/go2rtc`](https://hub.docker.com/r/alexxit/go2rtc) supports multiple architectures including `amd64`, `386`, `arm64`, and `arm`. This container offers the same functionality as the [Home Assistant add-on](#go2rtc-home-assistant-add-on) but is designed to operate independently of Home Assistant. It comes preinstalled with [FFmpeg](#source-ffmpeg) and [Python](#source-echo). +The Docker containers [`alexxit/go2rtc`](https://hub.docker.com/r/alexxit/go2rtc) and [`ghcr.io/alexxit/go2rtc`](https://github.com/AlexxIT/go2rtc/pkgs/container/go2rtc) supports multiple architectures including `386`, `amd64`, `arm/v6`, `arm/v7` and `arm64`. +This containers offers the same functionality as the Home Assistant [add-on](#go2rtc-home-assistant-add-on) but is designed to operate independently of Home Assistant. +It comes preinstalled with [FFmpeg](internal/ffmpeg/README.md) and [Python](internal/echo/README.md). -## go2rtc: Home Assistant add-on +### go2rtc: Home Assistant add-on [![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FAlexxIT%2Fhassio-addons) -1. Install Add-On: - - Settings > Add-ons > Plus > Repositories > Add `https://github.com/AlexxIT/hassio-addons` - - go2rtc > Install > Start -2. Setup [Integration](#module-hass) +1. Settings > Add-ons > Plus > Repositories > Add + ``` + https://github.com/AlexxIT/hassio-addons + ``` +2. go2rtc > Install > Start -## go2rtc: Home Assistant Integration +### go2rtc: Home Assistant Integration -[WebRTC Camera](https://github.com/AlexxIT/WebRTC) custom component can be used on any [Home Assistant installation](https://www.home-assistant.io/installation/), including [HassWP](https://github.com/AlexxIT/HassWP) on Windows. It can automatically download and use the latest version of go2rtc. Or it can connect to an existing version of go2rtc. Addon installation in this case is optional. +[WebRTC Camera](https://github.com/AlexxIT/WebRTC) custom component can be used on any Home Assistant [installation](https://www.home-assistant.io/installation/), including [HassWP](https://github.com/AlexxIT/HassWP) on Windows. It can automatically download and use the latest version of go2rtc. Or it can connect to an existing version of go2rtc. Addon installation in this case is optional. -## go2rtc: Dev version +### go2rtc: Master version Latest, but maybe unstable version: -- Binary: [latest nightly release](https://nightly.link/AlexxIT/go2rtc/workflows/build/master) +- Binary: [latest master build](https://nightly.link/AlexxIT/go2rtc/workflows/build/master) - Docker: `alexxit/go2rtc:master` or `alexxit/go2rtc:master-hardware` versions - Home Assistant add-on: `go2rtc master` or `go2rtc master hardware` versions -# Configuration +## Configuration + +This is the `go2rtc.yaml` file in [YAML-format](https://en.wikipedia.org/wiki/YAML). +The configuration can be changed in the [web interface](www/README.md) at `http://localhost:1984`. +The editor provides syntax highlighting and checking. + +The simplest config looks like this: + +```yaml +streams: + hall_camera: rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0 +``` - by default go2rtc will search `go2rtc.yaml` in the current work directory - `api` server will start on default **1984 port** (TCP) - `rtsp` server will start on default **8554 port** (TCP) - `webrtc` will use port **8555** (TCP/UDP) for connections -- `ffmpeg` will use default transcoding options - -Configuration options and a complete list of settings can be found in [the wiki](https://github.com/AlexxIT/go2rtc/wiki/Configuration). - -Available modules: - -- [streams](#module-streams) -- [api](#module-api) - HTTP API (important for WebRTC support) -- [rtsp](#module-rtsp) - RTSP Server (important for FFmpeg support) -- [webrtc](#module-webrtc) - WebRTC Server -- [mp4](#module-mp4) - MSE, MP4 stream and MP4 snapshot Server -- [hls](#module-hls) - HLS TS or fMP4 stream Server -- [mjpeg](#module-mjpeg) - MJPEG Server -- [ffmpeg](#source-ffmpeg) - FFmpeg integration -- [ngrok](#module-ngrok) - ngrok integration (external access for private network) -- [hass](#module-hass) - Home Assistant integration -- [log](#module-log) - logs config - -## Module: Streams - -**go2rtc** supports different stream source types. You can config one or multiple links of any type as a stream source. - -Available source types: - -- [rtsp](#source-rtsp) - `RTSP` and `RTSPS` cameras with [two-way audio](#two-way-audio) support -- [rtmp](#source-rtmp) - `RTMP` streams -- [http](#source-http) - `HTTP-FLV`, `MPEG-TS`, `JPEG` (snapshots), `MJPEG` streams -- [onvif](#source-onvif) - get camera `RTSP` link and snapshot link using `ONVIF` protocol -- [ffmpeg](#source-ffmpeg) - FFmpeg integration (`HLS`, `files` and many others) -- [ffmpeg:device](#source-ffmpeg-device) - local USB Camera or Webcam -- [exec](#source-exec) - get media from external app output -- [echo](#source-echo) - get stream link from bash or python -- [expr](#source-expr) - get stream link via built-in expression language -- [homekit](#source-homekit) - streaming from HomeKit Camera -- [bubble](#source-bubble) - streaming from ESeeCloud/dvr163 NVR -- [dvrip](#source-dvrip) - streaming from DVR-IP NVR -- [eseecloud](#source-eseecloud) - streaming from ESeeCloud/dvr163 NVR -- [tapo](#source-tapo) - TP-Link Tapo cameras with [two-way audio](#two-way-audio) support -- [ring](#source-ring) - Ring cameras with [two-way audio](#two-way-audio) support -- [tuya](#source-tuya) - Tuya cameras with [two-way audio](#two-way-audio) support -- [xiaomi](#source-xiaomi) - Xiaomi cameras with [two-way audio](#two-way-audio) support -- [kasa](#source-tapo) - TP-Link Kasa cameras -- [gopro](#source-gopro) - GoPro cameras -- [ivideon](#source-ivideon) - public cameras from [Ivideon](https://tv.ivideon.com/) service -- [hass](#source-hass) - Home Assistant integration -- [isapi](#source-isapi) - two-way audio for Hikvision (ISAPI) cameras -- [roborock](#source-roborock) - Roborock vacuums with cameras -- [doorbird](#source-doorbird) - Doorbird cameras with [two-way audio](#two-way-audio) support -- [webrtc](#source-webrtc) - WebRTC/WHEP sources -- [webtorrent](#source-webtorrent) - WebTorrent source from another go2rtc -- [wyze](#source-wyze) - Wyze cameras with [two-way audio](#two-way-audio) support - -Read more about [incoming sources](#incoming-sources) - -## Two-way audio - -Supported sources: - -- [RTSP cameras](#source-rtsp) with [ONVIF Profile T](https://www.onvif.org/specs/stream/ONVIF-Streaming-Spec.pdf) (back channel connection) -- [DVRIP](#source-dvrip) cameras -- [TP-Link Tapo](#source-tapo) cameras -- [Hikvision ISAPI](#source-isapi) cameras -- [Roborock vacuums](#source-roborock) models with cameras -- [Doorbird](#source-doorbird) cameras -- [Exec](#source-exec) audio on server -- [Ring](#source-ring) cameras -- [Tuya](#source-tuya) cameras -- [Wyze](#source-wyze) cameras -- [Xiaomi](#source-xiaomi) cameras -- [Any Browser](#incoming-browser) as IP-camera - -Two-way audio can be used in browser with [WebRTC](#module-webrtc) technology. The browser will give access to the microphone only for HTTPS sites ([read more](https://stackoverflow.com/questions/52759992/how-to-access-camera-and-microphone-in-chrome-without-https)). - -go2rtc also supports [play audio](#stream-to-camera) files and live streams on this cameras. - -## Source: RTSP - -```yaml -streams: - sonoff_camera: rtsp://rtsp:12345678@192.168.1.123/av_stream/ch0 - dahua_camera: - - rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0&unicast=true&proto=Onvif - - rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=1#backchannel=0 - amcrest_doorbell: - - rtsp://username:password@192.168.1.123:554/cam/realmonitor?channel=1&subtype=0#backchannel=0 - unifi_camera: rtspx://192.168.1.123:7441/fD6ouM72bWoFijxK - glichy_camera: ffmpeg:rtsp://username:password@192.168.1.123/live/ch00_1 -``` - -**Recommendations** - -- **Amcrest Doorbell** users may want to disable two-way audio, because with an active stream, you won't have a working call button. You need to add `#backchannel=0` to the end of your RTSP link in YAML config file -- **Dahua Doorbell** users may want to change [audio codec](https://github.com/AlexxIT/go2rtc/issues/49#issuecomment-2127107379) for proper two-way audio. Make sure not to request backchannel multiple times by adding `#backchannel=0` to other stream sources of the same doorbell. The `unicast=true&proto=Onvif` is preferred for two-way audio as this makes the doorbell accept multiple codecs for the incoming audio -- **Reolink** users may want NOT to use RTSP protocol at all, some camera models have a very awful, unusable stream implementation -- **Ubiquiti UniFi** users may want to disable HTTPS verification. Use `rtspx://` prefix instead of `rtsps://`. And don't use `?enableSrtp` [suffix](https://github.com/AlexxIT/go2rtc/issues/81) -- **TP-Link Tapo** users may skip login and password, because go2rtc supports login [without them](https://drmnsamoliu.github.io/video.html) -- If your camera has two RTSP links, you can add both as sources. This is useful when streams have different codecs, for example AAC audio with main stream and PCMU/PCMA audio with second stream -- If the stream from your camera is glitchy, try using [ffmpeg source](#source-ffmpeg). It will not add CPU load if you don't use transcoding -- If the stream from your camera is very glitchy, try to use transcoding with [ffmpeg source](#source-ffmpeg) - -**Other options** - -Format: `rtsp...#{param1}#{param2}#{param3}` - -- Add custom timeout `#timeout=30` (in seconds) -- Ignore audio - `#media=video` or ignore video - `#media=audio` -- Ignore two-way audio API `#backchannel=0` - important for some glitchy cameras -- Use WebSocket transport `#transport=ws...` - -**RTSP over WebSocket** - -```yaml -streams: - # WebSocket with authorization, RTSP - without - axis-rtsp-ws: rtsp://192.168.1.123:4567/axis-media/media.amp?overview=0&camera=1&resolution=1280x720&videoframeskipmode=empty&Axis-Orig-Sw=true#transport=ws://user:pass@192.168.1.123:4567/rtsp-over-websocket - # WebSocket without authorization, RTSP - with - dahua-rtsp-ws: rtsp://user:pass@192.168.1.123/cam/realmonitor?channel=1&subtype=1&proto=Private3#transport=ws://192.168.1.123/rtspoverwebsocket -``` - -## Source: RTMP - -You can get a stream from an RTMP server, for example [Nginx with nginx-rtmp-module](https://github.com/arut/nginx-rtmp-module). - -```yaml -streams: - rtmp_stream: rtmp://192.168.1.123/live/camera1 -``` - -## Source: HTTP - -Support Content-Type: - -- **HTTP-FLV** (`video/x-flv`) - same as RTMP, but over HTTP -- **HTTP-JPEG** (`image/jpeg`) - camera snapshot link, can be converted by go2rtc to MJPEG stream -- **HTTP-MJPEG** (`multipart/x`) - simple MJPEG stream over HTTP -- **MPEG-TS** (`video/mpeg`) - legacy [streaming format](https://en.wikipedia.org/wiki/MPEG_transport_stream) -Source also supports HTTP and TCP streams with autodetection for different formats: **MJPEG**, **H.264/H.265 bitstream**, **MPEG-TS**. - -```yaml -streams: - # [HTTP-FLV] stream in video/x-flv format - http_flv: http://192.168.1.123:20880/api/camera/stream/780900131155/657617 - - # [JPEG] snapshots from Dahua camera, will be converted to MJPEG stream - dahua_snap: http://admin:password@192.168.1.123/cgi-bin/snapshot.cgi?channel=1 - - # [MJPEG] stream will be proxied without modification - http_mjpeg: https://mjpeg.sanford.io/count.mjpeg - - # [MJPEG or H.264/H.265 bitstream or MPEG-TS] - tcp_magic: tcp://192.168.1.123:12345 - - # Add custom header - custom_header: "https://mjpeg.sanford.io/count.mjpeg#header=Authorization: Bearer XXX" -``` - -**PS.** Dahua camera has a bug: if you select MJPEG codec for RTSP second stream, snapshot won't work. - -## Source: ONVIF - -*[New in v1.5.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.5.0)* - -The source is not very useful if you already know RTSP and snapshot links for your camera. But it can be useful if you don't. - -**WebUI > Add** webpage support ONVIF autodiscovery. Your server must be on the same subnet as the camera. If you use Docker, you must use "network host". - -```yaml -streams: - dahua1: onvif://admin:password@192.168.1.123 - reolink1: onvif://admin:password@192.168.1.123:8000 - tapo1: onvif://admin:password@192.168.1.123:2020 -``` - -## Source: FFmpeg - -You can get any stream, file or device via FFmpeg and push it to go2rtc. The app will automatically start FFmpeg with the proper arguments when someone starts watching the stream. - -- FFmpeg preinstalled for **Docker** and **Home Assistant add-on** users -- **Home Assistant add-on** users can target files from [/media](https://www.home-assistant.io/more-info/local-media/setup-media/) folder - -Format: `ffmpeg:{input}#{param1}#{param2}#{param3}`. Examples: - -```yaml -streams: - # [FILE] all tracks will be copied without transcoding codecs - file1: ffmpeg:/media/BigBuckBunny.mp4 - - # [FILE] video will be transcoded to H264, audio will be skipped - file2: ffmpeg:/media/BigBuckBunny.mp4#video=h264 - - # [FILE] video will be copied, audio will be transcoded to PCMU - file3: ffmpeg:/media/BigBuckBunny.mp4#video=copy#audio=pcmu - - # [HLS] video will be copied, audio will be skipped - hls: ffmpeg:https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_16x9/gear5/prog_index.m3u8#video=copy - - # [MJPEG] video will be transcoded to H264 - mjpeg: ffmpeg:http://185.97.122.128/cgi-bin/faststream.jpg#video=h264 - - # [RTSP] video with rotation, should be transcoded, so select H264 - rotate: ffmpeg:rtsp://12345678@192.168.1.123/av_stream/ch0#video=h264#rotate=90 -``` - -All transcoding formats have [built-in templates](internal/ffmpeg/ffmpeg.go): `h264`, `h265`, `opus`, `pcmu`, `pcmu/16000`, `pcmu/48000`, `pcma`, `pcma/16000`, `pcma/48000`, `aac`, `aac/16000`. - -But you can override them via YAML config. You can also add your own formats to the config and use them with source params. - -```yaml -ffmpeg: - bin: ffmpeg # path to ffmpeg binary - global: "-hide_banner" - timeout: 5 # default timeout in seconds for rtsp inputs - h264: "-codec:v libx264 -g:v 30 -preset:v superfast -tune:v zerolatency -profile:v main -level:v 4.1" - mycodec: "-any args that supported by ffmpeg..." - myinput: "-fflags nobuffer -flags low_delay -timeout {timeout} -i {input}" - myraw: "-ss 00:00:20" -``` - -- You can use go2rtc stream name as ffmpeg input (ex. `ffmpeg:camera1#video=h264`) -- You can use `video` and `audio` params multiple times (ex. `#video=copy#audio=copy#audio=pcmu`) -- You can use `rotate` param with `90`, `180`, `270` or `-90` values, important with transcoding (ex. `#video=h264#rotate=90`) -- You can use `width` and/or `height` params, important with transcoding (ex. `#video=h264#width=1280`) -- You can use `drawtext` to add a timestamp (ex. `drawtext=x=2:y=2:fontsize=12:fontcolor=white:box=1:boxcolor=black`) - - This will greatly increase the CPU of the server, even with hardware acceleration -- You can use `timeout` param to set RTSP input timeout in seconds (ex. `#timeout=10`) -- You can use `raw` param for any additional FFmpeg arguments (ex. `#raw=-vf transpose=1`) -- You can use `input` param to override default input template (ex. `#input=rtsp/udp` will change RTSP transport from TCP to UDP+TCP) - - You can use raw input value (ex. `#input=-timeout {timeout} -i {input}`) - - You can add your own input templates - -Read more about [hardware acceleration](https://github.com/AlexxIT/go2rtc/wiki/Hardware-acceleration). - -**PS.** It is recommended to check the available hardware in the WebUI add page. - -## Source: FFmpeg Device - -You can get video from any USB camera or Webcam as RTSP or WebRTC stream. This is part of FFmpeg integration. - -- check available devices in web interface -- `video_size` and `framerate` must be supported by your camera! -- for Linux supported only video for now -- for macOS you can stream FaceTime camera or whole desktop! -- for macOS important to set right framerate - -Format: `ffmpeg:device?{input-params}#{param1}#{param2}#{param3}` - -```yaml -streams: - linux_usbcam: ffmpeg:device?video=0&video_size=1280x720#video=h264 - windows_webcam: ffmpeg:device?video=0#video=h264 - macos_facetime: ffmpeg:device?video=0&audio=1&video_size=1280x720&framerate=30#video=h264#audio=pcma -``` - -**PS.** It is recommended to check the available devices in the WebUI add page. - -## Source: Exec - -Exec source can run any external application and expect data from it. Two transports are supported - **pipe** (*from [v1.5.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.5.0)*) and **RTSP**. - -If you want to use **RTSP** transport, the command must contain the `{output}` argument in any place. On launch, it will be replaced by the local address of the RTSP server. - -**pipe** reads data from app stdout in different formats: **MJPEG**, **H.264/H.265 bitstream**, **MPEG-TS**. Also pipe can write data to app stdin in two formats: **PCMA** and **PCM/48000**. - -The source can be used with: - -- [FFmpeg](https://ffmpeg.org/) - go2rtc ffmpeg source just a shortcut to exec source -- [FFplay](https://ffmpeg.org/ffplay.html) - play audio on your server -- [GStreamer](https://gstreamer.freedesktop.org/) -- [Raspberry Pi Cameras](https://www.raspberrypi.com/documentation/computers/camera_software.html) -- any of your own software - -Pipe commands support parameters (format: `exec:{command}#{param1}#{param2}`): - -- `killsignal` - signal which will be sent to stop the process (numeric form) -- `killtimeout` - time in seconds for forced termination with sigkill -- `backchannel` - enable backchannel for two-way audio -- `starttimeout` - time in seconds for waiting first byte from RTSP - -```yaml -streams: - stream: exec:ffmpeg -re -i /media/BigBuckBunny.mp4 -c copy -rtsp_transport tcp -f rtsp {output} - picam_h264: exec:libcamera-vid -t 0 --inline -o - - picam_mjpeg: exec:libcamera-vid -t 0 --codec mjpeg -o - - pi5cam_h264: exec:libcamera-vid -t 0 --libav-format h264 -o - - canon: exec:gphoto2 --capture-movie --stdout#killsignal=2#killtimeout=5 - play_pcma: exec:ffplay -fflags nobuffer -f alaw -ar 8000 -i -#backchannel=1 - play_pcm48k: exec:ffplay -fflags nobuffer -f s16be -ar 48000 -i -#backchannel=1 -``` - -## Source: Echo - -Some sources may have a dynamic link. And you will need to get it using a Bash or Python script. Your script should echo a link to the source. RTSP, FFmpeg or any of the [supported sources](#module-streams). - -**Docker** and **Home Assistant add-on** users has preinstalled `python3`, `curl`, `jq`. - -Check examples in [wiki](https://github.com/AlexxIT/go2rtc/wiki/Source-Echo-examples). - -```yaml -streams: - apple_hls: echo:python3 hls.py https://developer.apple.com/streaming/examples/basic-stream-osx-ios5.html -``` - -## Source: Expr - -*[New in v1.8.2](https://github.com/AlexxIT/go2rtc/releases/tag/v1.8.2)* - -Like `echo` source, but uses the built-in [expr](https://github.com/antonmedv/expr) expression language. - -*[read more](internal/expr/README.md)* - -## Source: HomeKit - -**Important:** - -- You can use HomeKit Cameras **without Apple devices** (iPhone, iPad, etc.), it's just a yet another protocol -- HomeKit device can be paired with only one ecosystem. So, if you have paired it to an iPhone (Apple Home), you can't pair it with Home Assistant or go2rtc. Or if you have paired it to go2rtc, you can't pair it with an iPhone -- HomeKit device should be on the same network with working [mDNS](https://en.wikipedia.org/wiki/Multicast_DNS) between the device and go2rtc - -go2rtc supports importing paired HomeKit devices from [Home Assistant](#source-hass). So you can use HomeKit camera with Home Assistant and go2rtc simultaneously. If you are using Home Assistant, I recommend pairing devices with it; it will give you more options. - -You can pair device with go2rtc on the HomeKit page. If you can't see your devices, reload the page. Also, try rebooting your HomeKit device (power off). If you still can't see it, you have a problem with mDNS. - -If you see a device but it does not have a pairing button, it is paired to some ecosystem (Apple Home, Home Assistant, HomeBridge etc). You need to delete the device from that ecosystem, and it will be available for pairing. If you cannot unpair the device, you will have to reset it. - -**Important:** - -- HomeKit audio uses very non-standard **AAC-ELD** codec with very non-standard params and specification violations -- Audio can't be played in `VLC` and probably any other player -- Audio should be transcoded for use with MSE, WebRTC, etc. - -Recommended settings for using HomeKit Camera with WebRTC, MSE, MP4, RTSP: - -```yaml -streams: - aqara_g3: - - hass:Camera-Hub-G3-AB12 - - ffmpeg:aqara_g3#audio=aac#audio=opus -``` - -RTSP link with "normal" audio for any player: `rtsp://192.168.1.123:8554/aqara_g3?video&audio=aac` - -**This source is in active development!** Tested only with [Aqara Camera Hub G3](https://www.aqara.com/eu/product/camera-hub-g3) (both EU and CN versions). - -## Source: Bubble - -*[New in v1.6.1](https://github.com/AlexxIT/go2rtc/releases/tag/v1.6.1)* - -Other names: [ESeeCloud](http://www.eseecloud.com/), [dvr163](http://help.dvr163.com/). - -- you can skip `username`, `password`, `port`, `ch` and `stream` if they are default -- set up separate streams for different channels and streams - -```yaml -streams: - camera1: bubble://username:password@192.168.1.123:34567/bubble/live?ch=0&stream=0 -``` - -## Source: DVRIP - -*[New in v1.2.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.2.0)* - -Other names: DVR-IP, NetSurveillance, Sofia protocol (NETsurveillance ActiveX plugin XMeye SDK). - -- you can skip `username`, `password`, `port`, `channel` and `subtype` if they are default -- set up separate streams for different channels -- use `subtype=0` for Main stream, and `subtype=1` for Extra1 stream -- only the TCP protocol is supported - -```yaml -streams: - only_stream: dvrip://username:password@192.168.1.123:34567?channel=0&subtype=0 - only_tts: dvrip://username:password@192.168.1.123:34567?backchannel=1 - two_way_audio: - - dvrip://username:password@192.168.1.123:34567?channel=0&subtype=0 - - dvrip://username:password@192.168.1.123:34567?backchannel=1 -``` - -## Source: EseeCloud - -*[New in v1.9.10](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.10)* - -```yaml -streams: - camera1: eseecloud://user:pass@192.168.1.123:80/livestream/12 -``` - -## Source: Tapo - -*[New in v1.2.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.2.0)* - -[TP-Link Tapo](https://www.tapo.com/) proprietary camera protocol with **two-way audio** support. - -- stream quality is the same as [RTSP protocol](https://www.tapo.com/en/faq/34/) -- use the **cloud password**, this is not the RTSP password! you do not need to add a login! -- you can also use **UPPERCASE** MD5 hash from your cloud password with `admin` username -- some new camera firmwares require SHA256 instead of MD5 - -```yaml -streams: - # cloud password without username - camera1: tapo://cloud-password@192.168.1.123 - # admin username and UPPERCASE MD5 cloud-password hash - camera2: tapo://admin:UPPERCASE-MD5@192.168.1.123 - # admin username and UPPERCASE SHA256 cloud-password hash - camera3: tapo://admin:UPPERCASE-SHA256@192.168.1.123 - # VGA stream (the so called substream, the lower resolution one) - camera4: tapo://cloud-password@192.168.1.123?subtype=1 - # HD stream (default) - camera5: tapo://cloud-password@192.168.1.123?subtype=0 -``` - -```bash -echo -n "cloud password" | md5 | awk '{print toupper($0)}' -echo -n "cloud password" | shasum -a 256 | awk '{print toupper($0)}' -``` - -## Source: Kasa - -*[New in v1.7.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.7.0)* - -[TP-Link Kasa](https://www.kasasmart.com/) non-standard protocol [more info](https://medium.com/@hu3vjeen/reverse-engineering-tp-link-kc100-bac4641bf1cd). - -- `username` - urlsafe email, `alex@gmail.com` -> `alex%40gmail.com` -- `password` - base64password, `secret1` -> `c2VjcmV0MQ==` - -```yaml -streams: - kc401: kasa://username:password@192.168.1.123:19443/https/stream/mixed -``` - -Tested: KD110, KC200, KC401, KC420WS, EC71. - -## Source: Multitrans - -Two-way audio support for Chinese version of [TP-Link cameras](https://www.tp-link.com.cn/list_2549.html). - -*[read more](internal/multitrans/README.md)* - -## Source: Tuya - -*[New in v1.9.13](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.13)* - -[Tuya](https://www.tuya.com/) proprietary camera protocol with **two-way audio** support. Go2rtc supports `Tuya Smart API` and `Tuya Cloud API`. - -*[read more](internal/tuya/README.md)* - -## Source: Xiaomi - -*[New in v1.9.13](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.13)* - -This source allows you to view cameras from the [Xiaomi Mi Home](https://home.mi.com/) ecosystem. - -*[read more](internal/xiaomi/README.md)* - -## Source: Wyze - -This source allows you to stream from [Wyze](https://wyze.com/) cameras using native P2P protocol - no `docker-wyze-bridge` required. Supports H.264/H.265 video, AAC/G.711 audio, and two-way audio. - -*[read more](internal/wyze/README.md)* - -## Source: GoPro - -*[New in v1.8.3](https://github.com/AlexxIT/go2rtc/releases/tag/v1.8.3)* - -Support streaming from [GoPro](https://gopro.com/) cameras, connected via USB or Wi-Fi to Linux, Mac, Windows. - -*[read more](internal/gopro/README.md)* - -## Source: Ivideon - -Support public cameras from the service [Ivideon](https://tv.ivideon.com/). - -```yaml -streams: - quailcam: ivideon:100-tu5dkUPct39cTp9oNEN2B6/0 -``` - -## Source: Hass - -Support import camera links from [Home Assistant](https://www.home-assistant.io/) config files: - -- [Generic Camera](https://www.home-assistant.io/integrations/generic/), setup via GUI -- [HomeKit Camera](https://www.home-assistant.io/integrations/homekit_controller/) -- [ONVIF](https://www.home-assistant.io/integrations/onvif/) -- [Roborock](https://github.com/humbertogontijo/homeassistant-roborock) vacuums with camera - -```yaml -hass: - config: "/config" # skip this setting if you are a Home Assistant add-on user - -streams: - generic_camera: hass:Camera1 # Settings > Integrations > Integration Name - aqara_g3: hass:Camera-Hub-G3-AB12 -``` - -**WebRTC Cameras** (*from [v1.6.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.6.0)*) - -Any cameras in WebRTC format are supported. But at the moment Home Assistant only supports some [Nest](https://www.home-assistant.io/integrations/nest/) cameras in this format. - -**Important.** The Nest API only allows you to get a link to a stream for 5 minutes. Do not use this with Frigate! If the stream expires, Frigate will consume all available RAM on your machine within seconds. It's recommended to use [Nest source](#source-nest) - it supports extending the stream. - -```yaml -streams: - # link to Home Assistant Supervised - hass-webrtc1: hass://supervisor?entity_id=camera.nest_doorbell - # link to external Home Assistant with Long-Lived Access Tokens - hass-webrtc2: hass://192.168.1.123:8123?entity_id=camera.nest_doorbell&token=eyXYZ... -``` - -**RTSP Cameras** - -By default, the Home Assistant API does not allow you to get a dynamic RTSP link to a camera stream. [This method](https://github.com/felipecrs/hass-expose-camera-stream-source#importing-cameras-from-home-assistant-to-go2rtc-or-frigate) can work around it. - -## Source: ISAPI - -*[New in v1.3.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0)* - -This source type supports only backchannel audio for the Hikvision ISAPI protocol. So it should be used as a second source in addition to the RTSP protocol. - -```yaml -streams: - hikvision1: - - rtsp://admin:password@192.168.1.123:554/Streaming/Channels/101 - - isapi://admin:password@192.168.1.123:80/ -``` - -## Source: Nest - -*[New in v1.6.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.6.0)* - -Currently, only WebRTC cameras are supported. - -For simplicity, it is recommended to connect the Nest/WebRTC camera to the [Home Assistant](#source-hass). But if you can somehow get the below parameters, Nest/WebRTC source will work without Home Assistant. - -```yaml -streams: - nest-doorbell: nest:?client_id=***&client_secret=***&refresh_token=***&project_id=***&device_id=*** -``` - -## Source: Ring - -This source type supports Ring cameras with [two-way audio](#two-way-audio) support. If you have a `refresh_token` and `device_id`, you can use them in the `go2rtc.yaml` config file. Otherwise, you can use the go2rtc web interface and add your Ring account (WebUI > Add > Ring). Once added, it will list all your Ring cameras. - -```yaml -streams: - ring: ring:?device_id=XXX&refresh_token=XXX - ring_snapshot: ring:?device_id=XXX&refresh_token=XXX&snapshot -``` - -## Source: Roborock - -*[New in v1.3.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0)* - -This source type supports Roborock vacuums with cameras. Known working models: - -- Roborock S6 MaxV - only video (the vacuum has no microphone) -- Roborock S7 MaxV - video and two-way audio -- Roborock Qrevo MaxV - video and two-way audio - -This source supports loading Roborock credentials from the Home Assistant [custom integration](https://github.com/humbertogontijo/homeassistant-roborock) or the [core integration](https://www.home-assistant.io/integrations/roborock). Otherwise, you need to log in to your Roborock account (MiHome account is not supported). Go to go2rtc WebUI > Add webpage. Copy the `roborock://...` source for your vacuum and paste it into your `go2rtc.yaml` config. - -If you have a pattern PIN for your vacuum, add it as a numeric PIN (lines: 123, 456, 789) to the end of the `roborock` link. - -## Source: Doorbird - -This source type supports [Doorbird](https://www.doorbird.com/) devices including MJPEG stream, audio stream as well as two-way audio. - -*[read more](internal/doorbird/README.md)* - -## Source: WebRTC - -*[New in v1.3.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0)* - -This source type supports four connection formats. - -**whep** - -[WebRTC/WHEP](https://datatracker.ietf.org/doc/draft-murillo-whep/) is replaced by [WebRTC/WISH](https://datatracker.ietf.org/doc/charter-ietf-wish/02/) standard for WebRTC video/audio viewers. But it may already be supported in some third-party software. It is supported in go2rtc. - -**go2rtc** - -This format is only supported in go2rtc. Unlike WHEP, it supports asynchronous WebRTC connections and two-way audio. - -**openipc** (*from [v1.7.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.7.0)*) - -Support connection to [OpenIPC](https://openipc.org/) cameras. - -**wyze (via docker-wyze-bridge)** (*from [v1.6.1](https://github.com/AlexxIT/go2rtc/releases/tag/v1.6.1)*) - -Legacy method to connect to [Wyze](https://www.wyze.com/) cameras using WebRTC protocol via [docker-wyze-bridge](https://github.com/mrlt8/docker-wyze-bridge). For native P2P support without docker-wyze-bridge, see [Source: Wyze](#source-wyze). - -**kinesis** (*from [v1.6.1](https://github.com/AlexxIT/go2rtc/releases/tag/v1.6.1)*) - -Supports [Amazon Kinesis Video Streams](https://aws.amazon.com/kinesis/video-streams/), using WebRTC protocol. You need to specify the signalling WebSocket URL with all credentials in query params, `client_id` and `ice_servers` list in [JSON format](https://developer.mozilla.org/en-US/docs/Web/API/RTCIceServer). - -**switchbot** - -Support connection to [SwitchBot](https://us.switch-bot.com/) cameras that are based on Kinesis Video Streams. Specifically, this includes [Pan/Tilt Cam Plus 2K](https://us.switch-bot.com/pages/switchbot-pan-tilt-cam-plus-2k) and [Pan/Tilt Cam Plus 3K](https://us.switch-bot.com/pages/switchbot-pan-tilt-cam-plus-3k) and [Smart Video Doorbell](https://www.switchbot.jp/products/switchbot-smart-video-doorbell). `Outdoor Spotlight Cam 1080P`, `Outdoor Spotlight Cam 2K`, `Pan/Tilt Cam`, `Pan/Tilt Cam 2K`, `Indoor Cam` are based on Tuya, so this feature is not available. - -```yaml -streams: - webrtc-whep: webrtc:http://192.168.1.123:1984/api/webrtc?src=camera1 - webrtc-go2rtc: webrtc:ws://192.168.1.123:1984/api/ws?src=camera1 - webrtc-openipc: webrtc:ws://192.168.1.123/webrtc_ws#format=openipc#ice_servers=[{"urls":"stun:stun.kinesisvideo.eu-north-1.amazonaws.com:443"}] - webrtc-wyze: webrtc:http://192.168.1.123:5000/signaling/camera1?kvs#format=wyze - webrtc-kinesis: webrtc:wss://...amazonaws.com/?...#format=kinesis#client_id=...#ice_servers=[{...},{...}] - webrtc-switchbot: webrtc:wss://...amazonaws.com/?...#format=switchbot#resolution=hd#play_type=0#client_id=...#ice_servers=[{...},{...}] -``` - -**PS.** For `kinesis` sources, you can use [echo](#source-echo) to get connection params using `bash`, `python` or any other script language. - -## Source: WebTorrent - -*[New in v1.3.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0)* - -This source can get a stream from another go2rtc via [WebTorrent](#module-webtorrent) protocol. - -```yaml -streams: - webtorrent1: webtorrent:?share=huofssuxaty00izc&pwd=k3l2j9djeg8v8r7e -``` - -## Incoming sources - -By default, go2rtc establishes a connection to the source when any client requests it. Go2rtc drops the connection to the source when it has no clients left. - -- Go2rtc also can accepts incoming sources in [RTSP](#module-rtsp), [RTMP](#module-rtmp), [HTTP](#source-http) and **WebRTC/WHIP** formats -- Go2rtc won't stop such a source if it has no clients -- You can push data only to an existing stream (create a stream with empty source in config) -- You can push multiple incoming sources to the same stream -- You can push data to a non-empty stream, so it will have additional codecs inside - -**Examples** - -- RTSP with any codec - - ```yaml - ffmpeg -re -i BigBuckBunny.mp4 -c copy -rtsp_transport tcp -f rtsp rtsp://localhost:8554/camera1 - ``` - -- HTTP-MJPEG with MJPEG codec - - ```yaml - ffmpeg -re -i BigBuckBunny.mp4 -c mjpeg -f mpjpeg http://localhost:1984/api/stream.mjpeg?dst=camera1 - ``` - -- HTTP-FLV with H264, AAC codecs - - ```yaml - ffmpeg -re -i BigBuckBunny.mp4 -c copy -f flv http://localhost:1984/api/stream.flv?dst=camera1 - ``` - -- MPEG-TS with H264 codec - - ```yaml - ffmpeg -re -i BigBuckBunny.mp4 -c copy -f mpegts http://localhost:1984/api/stream.ts?dst=camera1 - ``` - -### Incoming: Browser - -*[New in v1.3.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0)* - -You can turn the browser of any PC or mobile into an IP camera with support for video and two-way audio. Or even broadcast your PC screen: - -1. Create empty stream in the `go2rtc.yaml` -2. Go to go2rtc WebUI -3. Open `links` page for your stream -4. Select `camera+microphone` or `display+speaker` option -5. Open `webrtc` local page (your go2rtc **should work over HTTPS!**) or `share link` via [WebTorrent](#module-webtorrent) technology (work over HTTPS by default) - -### Incoming: WebRTC/WHIP - -*[New in v1.3.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0)* - -You can use **OBS Studio** or any other broadcast software with [WHIP](https://www.ietf.org/archive/id/draft-ietf-wish-whip-01.html) protocol support. This standard has not yet been approved. But you can download OBS Studio [dev version](https://github.com/obsproject/obs-studio/actions/runs/3969201209): - -- Settings > Stream > Service: WHIP > `http://192.168.1.123:1984/api/webrtc?dst=camera1` - -## Stream to camera - -*[New in v1.3.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0)* - -go2rtc supports playing audio files (ex. music or [TTS](https://www.home-assistant.io/integrations/#text-to-speech)) and live streams (ex. radio) on cameras with [two-way audio](#two-way-audio) support (RTSP/ONVIF cameras, TP-Link Tapo, Hikvision ISAPI, Roborock vacuums, any Browser). - -API example: - -```text -POST http://localhost:1984/api/streams?dst=camera1&src=ffmpeg:http://example.com/song.mp3#audio=pcma#input=file -``` - -- you can stream: local files, web files, live streams or any format, supported by FFmpeg -- you should use [ffmpeg source](#source-ffmpeg) for transcoding audio to codec, that your camera supports -- you can check camera codecs on the go2rtc WebUI info page when the stream is active -- some cameras support only low quality `PCMA/8000` codec (ex. [Tapo](#source-tapo)) -- it is recommended to choose higher quality formats if your camera supports them (ex. `PCMA/48000` for some Dahua cameras) -- if you play files over `http` link, you need to add `#input=file` params for transcoding, so the file will be transcoded and played in real time -- if you play live streams, you should skip `#input` param, because it is already in real time -- you can stop active playback by calling the API with the empty `src` parameter -- you will see one active producer and one active consumer in go2rtc WebUI info page during streaming - -## Publish stream - -*[New in v1.8.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.8.0)* - -You can publish any stream to streaming services (YouTube, Telegram, etc.) via RTMP/RTMPS. Important: - -- Supported codecs: H264 for video and AAC for audio -- AAC audio is required for YouTube; videos without audio will not work -- You don't need to enable [RTMP module](#module-rtmp) listening for this task - -You can use the API: - -```text -POST http://localhost:1984/api/streams?src=camera1&dst=rtmps://... -``` - -Or config file: - -```yaml -publish: - # publish stream "video_audio_transcode" to Telegram - video_audio_transcode: - - rtmps://xxx-x.rtmp.t.me/s/xxxxxxxxxx:xxxxxxxxxxxxxxxxxxxxxx - # publish stream "audio_transcode" to Telegram and YouTube - audio_transcode: - - rtmps://xxx-x.rtmp.t.me/s/xxxxxxxxxx:xxxxxxxxxxxxxxxxxxxxxx - - rtmp://xxx.rtmp.youtube.com/live2/xxxx-xxxx-xxxx-xxxx-xxxx - -streams: - video_audio_transcode: - - ffmpeg:rtsp://user:pass@192.168.1.123/stream1#video=h264#hardware#audio=aac - audio_transcode: - - ffmpeg:rtsp://user:pass@192.168.1.123/stream1#video=copy#audio=aac -``` - -- **Telegram Desktop App** > Any public or private channel or group (where you admin) > Live stream > Start with... > Start streaming. -- **YouTube** > Create > Go live > Stream latency: Ultra low-latency > Copy: Stream URL + Stream key. - -## Preload stream +More information can be [found here](internal/app/README.md). + +## Features + +A summary table of all modules and features can be found [here](internal/README.md). + +### Streaming input + +#### public protocols + +- [`mpjpeg`](internal/mjpeg/README.md#mjpeg-client) - The legacy but still used [MJPEG](https://en.wikipedia.org/wiki/Motion_JPEG) protocol for real-time media transmission. +- [`onvif`](internal/onvif/README.md#onvif-client) - A popular [ONVIF](https://en.wikipedia.org/wiki/ONVIF) protocol for receiving media in RTSP format. +- [`rtmp`](internal/rtmp/README.md#rtmp-client) - The legacy but still used [RTMP](https://en.wikipedia.org/wiki/Real-Time_Messaging_Protocol) protocol for real-time media transmission. +- [`rtsp`](internal/rtsp/README.md#rtsp-client) - The most common [RTSP](https://en.wikipedia.org/wiki/Real-Time_Streaming_Protocol) protocol for real-time media transmission. +- [`webrtc`](internal/webrtc/README.md#webrtc-client) - [WebRTC](https://en.wikipedia.org/wiki/WebRTC) web-compatible protocol for real-time media transmission. +- [`yuv4mpegpipe`](internal/http/README.md#tcp) - Raw [YUV](https://en.wikipedia.org/wiki/Y%E2%80%B2UV) frame stream with [YUV4MPEG](https://manned.org/yuv4mpeg) header. + +#### private protocols + +- [`bubble`](internal/bubble/README.md) - Some NVR from [dvr163.com](http://help.dvr163.com/) and [eseecloud.com](http://www.eseecloud.com/). +- [`doorbird`](internal/doorbird/README.md) - [Doorbird](https://www.doorbird.com/) devices with two-way audio. +- [`dvrip`](internal/dvrip/README.md) - DVR-IP NVR, NetSurveillance, Sofia protocol (XMeye SDK). +- [`eseecloud`](internal/eseecloud/README.md) - Some NVR from [dvr163.com](http://help.dvr163.com/) and [eseecloud.com](http://www.eseecloud.com/). +- [`gopro`](internal/gopro/README.md) - [GoPro](https://gopro.com/) cameras, connected via USB or Wi-Fi. +- [`hass`](internal/hass/README.md) - Import cameras from [Home Assistant](https://www.home-assistant.io/) config files. +- [`homekit`](internal/homekit/README.md) - Cameras with [Apple HomeKit](https://www.apple.com/home-app/accessories/) protocol. +- [`isapi`](internal/isapi/README.md) - Two-way audio for [Hikvision ISAPI](https://tpp.hikvision.com/download/ISAPI_OTAP) protocol. +- [`kasa`](internal/tapo/README.md#tp-link-kasa) - [TP-Link Kasa](https://www.kasasmart.com/) cameras. +- [`multitrans`](internal/multitrans/README.md) - Two-way audio for Chinese version of [TP-Link](https://www.tp-link.com.cn/) cameras. +- [`nest`](internal/nest/README.md) - [Google Nest](https://developers.google.com/nest/device-access/supported-devices) cameras through user-unfriendly and paid APIs. +- [`ring`](internal/ring/README.md) - Ring cameras with two-way audio support. +- [`roborock`](internal/roborock/README.md) - [Roborock](https://roborock.com/) vacuums with cameras with two-way audio support. +- [`tapo`](internal/tapo/README.md) - [TP-Link Tapo](https://www.tapo.com/) cameras with two-way audio support. +- [`vigi`](internal/tapo/README.md#tp-link-vigi) - TP-Link Vigi cameras. +- [`tuya`](internal/tuya/README.md) - [Tuya](https://www.tuya.com/) ecosystem cameras with two-way audio support. +- [`webtorrent`](internal/webtorrent/README.md) - Stream from another go2rtc via [WebTorrent](https://en.wikipedia.org/wiki/WebTorrent) protocol. +- [`wyze`](internal/wyze/README.md) - [Wyze](https://wyze.com/) cameras using native P2P protocol +- [`xiaomi`](internal/xiaomi/README.md) - [Xiaomi Mi Home](https://home.mi.com/) ecosystem cameras with two-way audio support. + +#### devices + +- [`alsa`](internal/alsa/README.md) - A [framework](https://en.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture) for receiving audio from devices on Linux OS. +- [`v4l2`](internal/v4l2/README.md) - A [framework](https://en.wikipedia.org/wiki/Video4Linux) for receiving video from devices on Linux OS. + +#### files + +- [`adts`](internal/http/README.md#tcp) - Audio stream in [AAC](https://en.wikipedia.org/wiki/Advanced_Audio_Coding) codec with Audio Data Transport Stream headers. +- [`flv`](internal/http/README.md#tcp) - The legacy but still used [Flash Video](https://en.wikipedia.org/wiki/Flash_Video) format. +- [`h264`](internal/http/README.md#tcp) - AVC/H.264 bitstream. +- [`hevc`](internal/http/README.md#tcp) - HEVC/H.265 bitstream. +- [`hls`](internal/http/README.md) - A popular [HTTP Live Streaming](https://en.wikipedia.org/wiki/HTTP_Live_Streaming) format. +- [`mjpeg`](internal/http/README.md#tcp) - A continuous sequence of JPEG frames (without HTTP headers). +- [`mpegts`](internal/http/README.md#tcp) - The legacy [MPEG transport stream](https://en.wikipedia.org/wiki/MPEG_transport_stream) format. +- [`wav`](internal/http/README.md#tcp) - Audio stream in [Waveform Audio File](https://en.wikipedia.org/wiki/WAV) format. + +#### scripts + +- [`echo`](internal/echo/README.md) - If the source has a dynamic link, you can use a bash or python script to get it. +- [`exec`](internal/exec/README.md) - You can run an external application (`ffmpeg`, `gstreamer`, `rpicam`, etc.) and receive a media stream from it. +- [`expr`](internal/expr/README.md) - If the source has a dynamic link, you can use [Expr](https://github.com/expr-lang/expr) language to get it. +- [`ffmpeg`](internal/ffmpeg/README.md) - Use [FFmpeg](https://ffmpeg.org/) as a stream source. Hardware-accelerated transcoding and streaming from USB devices are supported. + +#### webrtc + +- [`creality`](internal/webrtc/README.md#creality) - [Creality](https://www.creality.com/) 3D printer cameras. +- [`kinesis`](internal/webrtc/README.md#kinesis) - [Amazon Kinesis](https://aws.amazon.com/kinesis/video-streams/) video streams. +- [`openipc`](internal/webrtc/README.md#openipc) - Cameras on open-source [OpenIPC](https://openipc.org/) firmware. +- [`switchbot`](internal/webrtc/README.md#switchbot) - [SwitchBot](https://us.switch-bot.com/) cameras. +- [`whep`](internal/webrtc/README.md#whep) - [WebRTC/WHEP](https://datatracker.ietf.org/doc/draft-murillo-whep/) is replaced by [WebRTC/WISH](https://datatracker.ietf.org/doc/charter-ietf-wish/02/) standard for WebRTC video/audio viewers. +- [`wyze`](internal/webrtc/README.md#wyze) - Legacy method to connect to [Wyze](https://www.wyze.com/) cameras via [docker-wyze-bridge](https://github.com/mrlt8/docker-wyze-bridge). + +### Streaming output + +- [`adts`](internal/mpegts/README.md) - Output stream in ADTS format with [AAC](https://en.wikipedia.org/wiki/Advanced_Audio_Coding) audio. +- [`ascii`](internal/mjpeg/README.md#ascii) - Just for fun stream as [ASCII to Terminal](https://www.youtube.com/watch?v=sHj_3h_sX7M). +- [`flv`](internal/rtmp/README.md) - Output stream in [Flash Video](https://en.wikipedia.org/wiki/Flash_Video) format. +- [`hls`](internal/hls/README.md) - Output stream in [HTTP Live Streaming](https://en.wikipedia.org/wiki/HTTP_Live_Streaming) format. +- [`homekit`](internal/homekit/README.md#homekit-server) - Output stream to [Apple Home](https://www.apple.com/home-app/) using [HomeKit](https://en.wikipedia.org/wiki/Apple_Home) protocol. +- [`jpeg`](internal/mjpeg/README.md#jpeg) - Output snapshots in [JPEG](https://en.wikipedia.org/wiki/JPEG) format. +- [`mpjpeg`](internal/mjpeg/README.md#mpjpeg) - Output a stream in [MJPEG](https://en.wikipedia.org/wiki/Motion_JPEG) format. +- [`mp4`](internal/mp4/README.md) - Output as [MP4 stream](https://en.wikipedia.org/wiki/Progressive_download) or [Media Source Extensions](https://developer.mozilla.org/en-US/docs/Web/API/Media_Source_Extensions_API) (MSE) compatible format. +- [`mpegts`](internal/homekit/README.md) - Output stream in [MPEG transport stream](https://en.wikipedia.org/wiki/MPEG_transport_stream) format. +- [`onvif`](internal/onvif/README.md#onvif-server) - Output stream using [ONVIF](https://en.wikipedia.org/wiki/ONVIF) protocol. +- [`rtmp`](internal/rtmp/README.md#rtmp-server) - Output stream using [Real-Time Messaging](https://en.wikipedia.org/wiki/Real-Time_Messaging_Protocol) protocol. +- [`rtsp`](internal/rtsp/README.md#rtsp-server) - Output stream using [Real-Time Streaming](https://en.wikipedia.org/wiki/Real-Time_Streaming_Protocol) protocol. +- [`webrtc`](internal/webrtc/README.md#webrtc-server) - Output stream using [Web Real-Time Communication](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API) API. +- [`webtorrent`](internal/webtorrent/README.md#webtorrent-server) - Output stream using [WebTorrent](https://en.wikipedia.org/wiki/WebTorrent) protocol. +- [`yuv4mpegpipe`](internal/mjpeg/README.md#yuv4mpegpipe) - Output in raw [YUV](https://en.wikipedia.org/wiki/Y%E2%80%B2UV) frame stream with [YUV4MPEG](https://manned.org/yuv4mpeg) header. + +### Streaming ingest + +Supported for: +[`flv`](internal/rtmp/README.md#flv-server), +[`mjpeg`](internal/mjpeg/README.md#streaming-ingest), +[`mpegts`](internal/mpegts/README.md#streaming-ingest), +[`rtmp`](internal/rtmp/README.md#rtmp-server), +[`rtsp`](internal/rtsp/README.md#streaming-ingest), +[`webrtc`](internal/webrtc/README.md#streaming-ingest). + +This is a feature when go2rtc expects to receive an incoming stream from an external application. The stream transmission is started and stopped by an external application. + +- You can push data only to an existing stream (create a stream with empty source in config). +- You can push multiple incoming sources to the same stream. +- You can push data to a non-empty stream, so it will have additional codecs inside. + +### Two-way audio + +Supported for: +[`doorbird`](internal/doorbird/README.md), +[`dvrip`](internal/dvrip/README.md), +[`exec`](internal/exec/README.md), +[`isapi`](internal/isapi/README.md), +[`multitrans`](internal/multitrans/README.md), +[`ring`](internal/ring/README.md), +[`roborock`](internal/roborock/README.md), +[`rtsp`](internal/rtsp/README.md#two-way-audio), +[`tapo`](internal/tapo/README.md), +[`tuya`](internal/tuya/README.md), +[`webrtc`](internal/webrtc/README.md), +[`wyze`](internal/wyze/README.md), +[`xiaomi`](internal/xiaomi/README.md). + +Two-way audio can be used in browser with [WebRTC](internal/webrtc/README.md) technology. The browser will give access to the microphone only for HTTPS sites ([read more](https://stackoverflow.com/questions/52759992/how-to-access-camera-and-microphone-in-chrome-without-https)). + +### Stream to camera + +You can play audio files or live streams on any camera with [two-way audio](#two-way-audio) support. + +[read more](internal/streams/README.md#stream-to-camera) + +### Publish stream + +You can publish any stream to streaming services (YouTube, Telegram, etc.) via RTMP/RTMPS. + +[read more](internal/streams/README.md#publish-stream) + +### Preload stream You can preload any stream on go2rtc start. This is useful for cameras that take a long time to start up. -```yaml -preload: - camera1: # default: video&audio = ANY - camera2: "video" # preload only video track - camera3: "video=h264&audio=opus" # preload H264 video and OPUS audio +[read more](internal/streams/README.md#preload-stream) -streams: - camera1: - - rtsp://192.168.1.100/stream - camera2: - - rtsp://192.168.1.101/stream - camera3: - - rtsp://192.168.1.102/h265stream - - ffmpeg:camera3#video=h264#audio=opus#hardware +## Codecs + +If you have questions about why video or audio is not displayed, you need to read the following sections. + +| Name | FFmpeg | RTSP | Aliases | +|------------------------------|----------|---------------|-------------| +| Advanced Audio Coding | `aac` | MPEG4-GENERIC | | +| Advanced Video Coding | `h264` | H264 | AVC, H.264 | +| G.711 PCM (A-law) | `alaw` | PCMA | G711A | +| G.711 PCM (µ-law) | `mulaw` | PCMU | G711u | +| High Efficiency Video Coding | `hevc` | H265 | HEVC, H.265 | +| Motion JPEG | `mpjpeg` | JPEG | | +| MPEG-1 Audio Layer III | `mp3` | MPA | | +| Opus Codec | `opus` | OPUS | | +| PCM signed 16-bit big-endian | `s16be` | L16 | | + +### Codecs filters + +go2rtc can automatically detect which codecs your device supports for [WebRTC](internal/webrtc/README.md) and [MSE](internal/mp4/README.md) technologies. + +But it cannot be done for [RTSP](internal/rtsp/README.md), [HTTP progressive streaming](internal/mp4/README.md), [HLS](internal/hls/README.md) technologies. +You can manually add a codec filter when you create a link to a stream. +The filters work the same for all three technologies. +Filters do not create a new codec, they only select the suitable codec from existing sources. +You can add new codecs to the stream using the [FFmpeg transcoding](internal/ffmpeg/README.md). + +Without filters: + +- RTSP will provide only the first video and only the first audio (any codec) +- MP4 will include only compatible codecs (H264, H265, AAC) +- HLS will output in the legacy TS format (H264 without audio) + +Some examples: + +- `rtsp://192.168.1.123:8554/camera1?mp4` - useful for recording as MP4 files (e.g. Home Assistant or Frigate) +- `rtsp://192.168.1.123:8554/camera1?video=h264,h265&audio=aac` - full version of the filter above +- `rtsp://192.168.1.123:8554/camera1?video=h264&audio=aac&audio=opus` - H264 video codec and two separate audio tracks +- `rtsp://192.168.1.123:8554/camera1?video&audio=all` - any video codec and all audio codecs as separate tracks +- `http://192.168.1.123:1984/api/stream.m3u8?src=camera1&mp4` - HLS stream with MP4 compatible codecs (HLS/fMP4) +- `http://192.168.1.123:1984/api/stream.m3u8?src=camera1&mp4=flac` - HLS stream with PCMA/PCMU/PCM audio support (HLS/fMP4), won't work on old devices +- `http://192.168.1.123:1984/api/stream.mp4?src=camera1&mp4=flac` - MP4 file with PCMA/PCMU/PCM audio support, won't work on old devices (ex. iOS 12) +- `http://192.168.1.123:1984/api/stream.mp4?src=camera1&mp4=all` - MP4 file with non-standard audio codecs, won't work on some players + +### Codecs madness + +`AVC/H.264` video can be played almost anywhere. But `HEVC/H.265` has many limitations in supporting different devices and browsers. + +| Device | WebRTC | MSE | HTTP* | HLS | +|--------------------------------------------------------------------|-----------------------------------------|-----------------------------------------|----------------------------------------------|-----------------------------| +| *latency* | best | medium | bad | bad | +| Desktop Chrome 136+
Desktop Edge
Android Chrome 136+ | H264, H265*
PCMU, PCMA
OPUS | H264, H265*
AAC, FLAC*
OPUS | H264, H265*
AAC, FLAC*
OPUS, MP3 | no | +| Desktop Firefox | H264
PCMU, PCMA
OPUS | H264
AAC, FLAC*
OPUS | H264
AAC, FLAC*
OPUS | no | +| Desktop Safari 14+
iPad Safari 14+
iPhone Safari 17.1+ | H264, H265*
PCMU, PCMA
OPUS | H264, H265
AAC, FLAC* | **no!** | H264, H265
AAC, FLAC* | +| iPhone Safari 14+ | H264, H265*
PCMU, PCMA
OPUS | **no!** | **no!** | H264, H265
AAC, FLAC* | +| macOS [Hass App][1] | no | no | no | H264, H265
AAC, FLAC* | + +[1]: https://apps.apple.com/app/home-assistant/id1099568401 + +- `HTTP*` - HTTP Progressive Streaming, not related to [progressive download](https://en.wikipedia.org/wiki/Progressive_download), because the file has no size and no end +- `WebRTC H265` - supported in [Chrome 136+](https://developer.chrome.com/release-notes/136), supported in [Safari 18+](https://developer.apple.com/documentation/safari-release-notes/safari-18-release-notes) +- `MSE iPhone` - supported in [iOS 17.1+](https://webkit.org/blog/14735/webkit-features-in-safari-17-1/) + +**Audio** + +- go2rtc supports [automatic repackaging](#built-in-transcoding) of `PCMA/PCMU/PCM` codecs into `FLAC` for MSE/MP4/HLS so they'll work almost anywhere +- **WebRTC** audio codecs: `PCMU/8000`, `PCMA/8000`, `OPUS/48000/2` +- `OPUS` and `MP3` inside **MP4** are part of the standard, but some players do not support them anyway (especially Apple) + +**Apple devices** + +- all Apple devices don't support HTTP progressive streaming +- old iPhone firmwares don't support MSE technology because it competes with the HTTP Live Streaming (HLS) technology, invented by Apple +- HLS is the worst technology for **live** streaming, it still exists only because of iPhones + +### Built-in transcoding + +There are no plans to embed complex transcoding algorithms inside go2rtc. +[FFmpeg source](internal/ffmpeg/README.md) does a great job with this. +Including [hardware acceleration](https://github.com/AlexxIT/go2rtc/wiki/Hardware-acceleration) support. + +But go2rtc has some simple algorithms. They are turned on automatically; you do not need to set them up additionally. + +**PCM for MSE/MP4/HLS** + +Go2rtc can pack `PCMA`, `PCMU` and `PCM` codecs into an MP4 container so that they work in all browsers and all built-in players on modern devices. Including Apple QuickTime: + +```text +PCMA/PCMU => PCM => FLAC => MSE/MP4/HLS ``` -## Module: API +**Resample PCMA/PCMU for WebRTC** -The HTTP API is the main part for interacting with the application. Default address: `http://localhost:1984/`. +By default WebRTC supports only `PCMA/8000` and `PCMU/8000`. But go2rtc can automatically resample PCMA and PCMU codecs with a different sample rate. Also, go2rtc can transcode `PCM` codec to `PCMA/8000`, so WebRTC can play it: -**Important!** go2rtc passes requests from localhost and Unix sockets without HTTP authorization, even if you have it configured. It is your responsibility to set up secure external access to the API. If not properly configured, an attacker can gain access to your cameras and even your server. - -[API description](api/README.md). - -**Module config** - -- you can disable HTTP API with `listen: ""` and use, for example, only RTSP client/server protocol -- you can enable HTTP API only on localhost with `listen: "127.0.0.1:1984"` setting -- you can change the API `base_path` and host go2rtc on your main app webserver suburl -- all files from `static_dir` hosted on root path: `/` -- you can use raw TLS cert/key content or path to files - -```yaml -api: - listen: ":1984" # default ":1984", HTTP API port ("" - disabled) - username: "admin" # default "", Basic auth for WebUI - password: "pass" # default "", Basic auth for WebUI - local_auth: true # default false, Enable auth check for localhost requests - base_path: "/rtc" # default "", API prefix for serving on suburl (/api => /rtc/api) - static_dir: "www" # default "", folder for static files (custom web interface) - origin: "*" # default "", allow CORS requests (only * supported) - tls_listen: ":443" # default "", enable HTTPS server - tls_cert: | # default "", PEM-encoded fullchain certificate for HTTPS - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- - tls_key: | # default "", PEM-encoded private key for HTTPS - -----BEGIN PRIVATE KEY----- - ... - -----END PRIVATE KEY----- - unix_listen: "/tmp/go2rtc.sock" # default "", unix socket listener for API +```text +PCM/xxx => PCMA/8000 => WebRTC +PCMA/xxx => PCMA/8000 => WebRTC +PCMU/xxx => PCMU/8000 => WebRTC ``` -**PS:** - -- MJPEG over WebSocket plays better than native MJPEG because Chrome [bug](https://bugs.chromium.org/p/chromium/issues/detail?id=527446) -- MP4 over WebSocket was created only for Apple iOS because it doesn't support MSE and native MP4 - -## Module: RTSP - -You can get any stream as RTSP-stream: `rtsp://192.168.1.123:8554/{stream_name}` - -You can enable external password protection for your RTSP streams. Password protection is always disabled for localhost calls (ex. FFmpeg or Home Assistant on the same server). - -```yaml -rtsp: - listen: ":8554" # RTSP Server TCP port, default - 8554 - username: "admin" # optional, default - disabled - password: "pass" # optional, default - disabled - default_query: "video&audio" # optional, default codecs filters -``` - -By default go2rtc provide RTSP-stream with only one first video and only one first audio. You can change it with the `default_query` setting: - -- `default_query: "mp4"` - MP4 compatible codecs (H264, H265, AAC) -- `default_query: "video=all&audio=all"` - all tracks from all source (not all players can handle this) -- `default_query: "video=h264,h265"` - only one video track (H264 or H265) -- `default_query: "video&audio=all"` - only one first any video and all audio as separate tracks - -Read more about [codecs filters](#codecs-filters). - -## Module: RTMP - -*[New in v1.8.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.8.0)* - -You can get any stream as RTMP-stream: `rtmp://192.168.1.123/{stream_name}`. Only H264/AAC codecs supported right now. - -[Incoming stream](#incoming-sources) in RTMP format tested only with [OBS Studio](https://obsproject.com/) and a Dahua camera. Different FFmpeg versions have different problems with this format. - -```yaml -rtmp: - listen: ":1935" # by default - disabled! -``` - -## Module: WebRTC - -In most cases, [WebRTC](https://en.wikipedia.org/wiki/WebRTC) uses a direct peer-to-peer connection from your browser to go2rtc and sends media data via UDP. -It **can't pass** media data through your Nginx or Cloudflare or [Nabu Casa](https://www.nabucasa.com/) HTTP TCP connection! -It can automatically detect your external IP via a public [STUN](https://en.wikipedia.org/wiki/STUN) server. -It can establish an external direct connection via [UDP hole punching](https://en.wikipedia.org/wiki/UDP_hole_punching) technology even if you do not open your server to the World. - -But about 10-20% of users may need to configure additional settings for external access if **mobile phone** or **go2rtc server** is behind [Symmetric NAT](https://tomchen.github.io/symmetric-nat-test/). - -- by default, WebRTC uses both TCP and UDP on port 8555 for connections -- you can use this port for external access -- you can change the port in YAML config: - -```yaml -webrtc: - listen: ":8555" # address of your local server and port (TCP/UDP) -``` - -**Static public IP** - -- forward the port 8555 on your router (you can use the same 8555 port or any other as external port) -- add your external IP address and external port to the YAML config - -```yaml -webrtc: - candidates: - - 216.58.210.174:8555 # if you have a static public IP address -``` - -**Dynamic public IP** - -- forward the port 8555 on your router (you can use the same 8555 port or any other as the external port) -- add `stun` word and external port to YAML config - - go2rtc automatically detects your external address with STUN server - -```yaml -webrtc: - candidates: - - stun:8555 # if you have a dynamic public IP address -``` - -**Hard tech way 1. Own TCP-tunnel** - -If you have a personal [VPS](https://en.wikipedia.org/wiki/Virtual_private_server), you can create a TCP tunnel and setup in the same way as "Static public IP". But use your VPS IP address in the YAML config. - -**Hard tech way 2. Using TURN-server** - -If you have personal [VPS](https://en.wikipedia.org/wiki/Virtual_private_server), you can install TURN server (e.g. [coturn](https://github.com/coturn/coturn), config [example](https://github.com/AlexxIT/WebRTC/wiki/Coturn-Example)). - -```yaml -webrtc: - ice_servers: - - urls: [stun:stun.l.google.com:19302] - - urls: [turn:123.123.123.123:3478] - username: your_user - credential: your_pass -``` - -## Module: HomeKit - -*[New in v1.7.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.7.0)* - -HomeKit module can work in two modes: - -- export any H264 camera to Apple HomeKit -- transparent proxy any Apple HomeKit camera (Aqara, Eve, Eufy, etc.) back to Apple HomeKit, so you will have all camera features in Apple Home and also will have RTSP/WebRTC/MP4/etc. from your HomeKit camera - **Important** -- HomeKit cameras support only H264 video and OPUS audio +- FLAC codec not supported in an RTSP stream. If you are using Frigate or Home Assistant for recording MP4 files with PCMA/PCMU/PCM audio, you should set up transcoding to the AAC codec. +- PCMA and PCMU are VERY low-quality codecs. They support only 256! different sounds. Use them only when you have no other options. -**Minimal config** +### Codecs negotiation + +For example, you want to watch an RTSP stream from a [Dahua IPC-K42](https://www.dahuasecurity.com/fr/products/All-Products/Network-Cameras/Wireless-Series/Wi-Fi-Series/4MP/IPC-K42) camera in your Chrome browser. + +- this camera supports two-way audio standard **ONVIF Profile T** +- this camera supports codecs **H264, H265** for sending video, and you select `H264` in camera settings +- this camera supports codecs **AAC, PCMU, PCMA** for sending audio (from mic), and you select `AAC/16000` in camera settings +- this camera supports codecs **AAC, PCMU, PCMA** for receiving audio (to speaker), you don't need to select them +- your browser supports codecs **H264, VP8, VP9, AV1** for receiving video, you don't need to select them +- your browser supports codecs **OPUS, PCMU, PCMA** for sending and receiving audio, you don't need to select them +- you can't get the camera audio directly because its audio codecs don't match your browser's codecs + - so you decide to use transcoding via FFmpeg and add this setting to the config YAML file + - you have chosen `OPUS/48000/2` codec, because it is higher quality than the `PCMU/8000` or `PCMA/8000` + +Now you have a stream with two sources - **RTSP and FFmpeg**: ```yaml streams: - dahua1: rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0 -homekit: - dahua1: # same stream ID from streams list, default PIN - 19550224 + dahua: + - rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0&unicast=true&proto=Onvif + - ffmpeg:rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0#audio=opus ``` -**Full config** +**go2rtc** automatically matches codecs for your browser across all of your stream sources. This is called **multi-source two-way codec negotiation**, and it's one of the main features of this app. -```yaml -streams: - dahua1: - - rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0 - - ffmpeg:dahua1#video=h264#hardware # if your camera doesn't support H264, important for HomeKit - - ffmpeg:dahua1#audio=opus # only OPUS audio supported by HomeKit +**PS.** You can select `PCMU` or `PCMA` codec in camera settings and not use transcoding at all. Or you can select `AAC` codec for main stream and `PCMU` codec for second stream and add both RTSP to YAML config, this also will work fine. -homekit: - dahua1: # same stream ID from streams list - pin: 12345678 # custom PIN, default: 19550224 - name: Dahua camera # custom camera name, default: generated from stream ID - device_id: dahua1 # custom ID, default: generated from stream ID - device_private: dahua1 # custom key, default: generated from stream ID -``` - -**Proxy HomeKit camera** - -- Video stream from HomeKit camera to Apple device (iPhone, AppleTV) will be transmitted directly -- Video stream from HomeKit camera to RTSP/WebRTC/MP4/etc. will be transmitted via go2rtc - -```yaml -streams: - aqara1: - - homekit://... - - ffmpeg:aqara1#audio=aac#audio=opus # optional audio transcoding - -homekit: - aqara1: # same stream ID from streams list -``` - -## Module: WebTorrent - -*[New in v1.3.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0)* - -This module supports: - -- Share any local stream via [WebTorrent](https://webtorrent.io/) technology -- Get any [incoming stream](#incoming-browser) from PC or mobile via [WebTorrent](https://webtorrent.io/) technology -- Get any remote [go2rtc source](#source-webtorrent) via [WebTorrent](https://webtorrent.io/) technology - -Securely and freely. You do not need to open a public access to the go2rtc server. But in some cases (Symmetric NAT), you may need to set up external access to [WebRTC module](#module-webrtc). - -To generate a sharing link or incoming link, go to the go2rtc WebUI (stream links page). This link is **temporary** and will stop working after go2rtc is restarted! - -You can create permanent external links in the go2rtc config: - -```yaml -webtorrent: - shares: - super-secret-share: # share name, should be unique among all go2rtc users! - pwd: super-secret-password - src: rtsp-dahua1 # stream name from streams section -``` - -Link example: `https://go2rtc.org/webtorrent/#share=02SNtgjKXY&pwd=wznEQqznxW&media=video+audio` - -## Module: ngrok - -With [ngrok](https://ngrok.com/) integration, you can get external access to your streams in situations when you have internet with a private IP address. - -*[read more](internal/ngrok/README.md)* - -## Module: Hass - -While [go2rtc is used by default in Home Assistant](https://www.home-assistant.io/integrations/go2rtc/), the best and easiest way to have full control over it is to install the [WebRTC Camera](#go2rtc-home-assistant-integration) custom integration and card. - -You have several options on how to add a camera to Home Assistant: - -1. Camera RTSP source => [Generic Camera](https://www.home-assistant.io/integrations/generic/) -2. Camera [any source](#module-streams) => [go2rtc config](#configuration) => [Generic Camera](https://www.home-assistant.io/integrations/generic/) - - Install any [go2rtc](#fast-start) - - Add your stream to [go2rtc config](#configuration) - - Home Assistant > Settings > Integrations > Add Integration > [ONVIF](https://my.home-assistant.io/redirect/config_flow_start/?domain=onvif) > Host: `127.0.0.1`, Port: `1984` - - Home Assistant > Settings > Integrations > Add Integration > [Generic Camera](https://my.home-assistant.io/redirect/config_flow_start/?domain=generic) > Stream Source URL: `rtsp://127.0.0.1:8554/camera1` (change to your stream name, leave everything else as is) - -You have several options on how to watch the stream from the cameras in Home Assistant: - -1. `Camera Entity` => `Picture Entity Card` => Technology `WebRTC` (through [built-in go2rtc](https://www.home-assistant.io/integrations/go2rtc/)), codecs `H264/H265/AAC/PCMU/PCMA/OPUS`, best latency. Fallbacks to: Technology `HLS`, codecs: `H264/H265/AAC`, poor latency. -2. `Camera Entity` or `Camera URL` => [WebRTC Camera](https://github.com/AlexxIT/WebRTC) => Technology: `WebRTC/MSE/MP4/MJPEG`, codecs: `H264/H265/AAC/PCMU/PCMA/OPUS`, best latency, best compatibility. - - Install and add [WebRTC Camera](https://github.com/AlexxIT/WebRTC) custom integration - - Use WebRTC Camera custom card in your dashboard - -You can add camera `entity_id` to [go2rtc config](#configuration) if you need transcoding: - -```yaml -streams: - "camera.hall": ffmpeg:{input}#video=copy#audio=opus -``` - -**PS.** Default Home Assistant cards don't support two-way audio. You can use two-way audio from the [add-on Web UI](https://my.home-assistant.io/redirect/supervisor_addon/?addon=a889bffc_go2rtc&repository_url=https%3A%2F%2Fgithub.com%2FAlexxIT%2Fhassio-addons), but you need to use HTTPS to access the microphone. This is a browser restriction and cannot be avoided. - -**PS.** There is also another nice card with two-way audio support through go2rtc - [Advanced Camera Card](https://github.com/dermotduffy/advanced-camera-card). - -## Module: MP4 - -Provides several features: - -1. MSE stream (fMP4 over WebSocket) -2. Camera snapshots in MP4 format (single frame), can be sent to [Telegram](https://github.com/AlexxIT/go2rtc/wiki/Snapshot-to-Telegram) -3. HTTP progressive streaming (MP4 file stream) - bad format for streaming because of high start delay. This format doesn't work in all Safari browsers, but go2rtc will automatically redirect it to HLS/fMP4 in this case. - -API examples: - -- MP4 snapshot: `http://192.168.1.123:1984/api/frame.mp4?src=camera1` (H264, H265) -- MP4 stream: `http://192.168.1.123:1984/api/stream.mp4?src=camera1` (H264, H265, AAC) -- MP4 file: `http://192.168.1.123:1984/api/stream.mp4?src=camera1` (H264, H265*, AAC, OPUS, MP3, PCMA, PCMU, PCM) - - You can use `mp4`, `mp4=flac` and `mp4=all` param for codec filters - - You can use `duration` param in seconds (ex. `duration=15`) - - You can use `filename` param (ex. `filename=record.mp4`) - - You can use `rotate` param with `90`, `180` or `270` values - - You can use `scale` param with positive integer values (ex. `scale=4:3`) - -Read more about [codecs filters](#codecs-filters). - -**PS.** Rotate and scale params don't use transcoding and change video using metadata. - -## Module: HLS - -*[New in v1.1.0](https://github.com/AlexxIT/go2rtc/releases/tag/v1.1.0)* - -[HLS](https://en.wikipedia.org/wiki/HTTP_Live_Streaming) is the worst technology for real-time streaming. It can only be useful on devices that do not support more modern technology, like [WebRTC](#module-webrtc), [MSE/MP4](#module-mp4). - -The go2rtc implementation differs from the standards and may not work with all players. - -API examples: - -- HLS/TS stream: `http://192.168.1.123:1984/api/stream.m3u8?src=camera1` (H264) -- HLS/fMP4 stream: `http://192.168.1.123:1984/api/stream.m3u8?src=camera1&mp4` (H264, H265, AAC) - -Read more about [codecs filters](#codecs-filters). - -## Module: MJPEG - -- This module can provide and receive streams in MJPEG format. -- This module is also responsible for receiving snapshots in JPEG format. -- This module also supports streaming to the server console (terminal) in the **animated ASCII art** format. - -*[read more](internal/mjpeg/README.md)* - -## Module: Log - -You can set different log levels for different modules. - -```yaml -log: - level: info # default level - api: trace - exec: debug - rtsp: warn - streams: error - webrtc: fatal -``` - -# Security +## Security > [!IMPORTANT] > If an attacker gains access to the API, you are in danger. Through the API, an attacker can use insecure sources such as echo and exec. And get full access to your server. @@ -1295,138 +468,16 @@ webrtc: listen: ":8555" # external TCP/UDP port ``` -- local access to RTSP is not a problem for [FFmpeg](#source-ffmpeg) integration, because it runs locally on your server +- local access to RTSP is not a problem for [FFmpeg](internal/ffmpeg/README.md) integration, because it runs locally on your server - local access to API is not a problem for the [Home Assistant add-on](#go2rtc-home-assistant-add-on), because Home Assistant runs locally on the same server, and the add-on web UI is protected with Home Assistant authorization ([Ingress feature](https://www.home-assistant.io/blog/2019/04/15/hassio-ingress/)) - external access to WebRTC TCP port is not a problem, because it is used only for transmitting encrypted media data - - anyway you need to open this port to your local network and to the Internet for WebRTC to work + - anyway you need to open this port to your local network and to the Internet for WebRTC to work If you need web interface protection without the Home Assistant add-on, you need to use a reverse proxy, like [Nginx](https://nginx.org/), [Caddy](https://caddyserver.com/), etc. PS. Additionally, WebRTC will try to use the 8555 UDP port to transmit encrypted media. It works without problems on the local network, and sometimes also works for external access, even if you haven't opened this port on your router ([read more](https://en.wikipedia.org/wiki/UDP_hole_punching)). But for stable external WebRTC access, you need to open the 8555 port on your router for both TCP and UDP. -# Codecs filters - -go2rtc can automatically detect which codecs your device supports for [WebRTC](#module-webrtc) and [MSE](#module-mp4) technologies. - -But it cannot be done for [RTSP](#module-rtsp), [HTTP progressive streaming](#module-mp4), [HLS](#module-hls) technologies. You can manually add a codec filter when you create a link to a stream. The filters work the same for all three technologies. Filters do not create a new codec. They only select the suitable codec from existing sources. You can add new codecs to the stream using the [FFmpeg transcoding](#source-ffmpeg). - -Without filters: - -- RTSP will provide only the first video and only the first audio (any codec) -- MP4 will include only compatible codecs (H264, H265, AAC) -- HLS will output in the legacy TS format (H264 without audio) - -Some examples: - -- `rtsp://192.168.1.123:8554/camera1?mp4` - useful for recording as MP4 files (e.g. Home Assistant or Frigate) -- `rtsp://192.168.1.123:8554/camera1?video=h264,h265&audio=aac` - full version of the filter above -- `rtsp://192.168.1.123:8554/camera1?video=h264&audio=aac&audio=opus` - H264 video codec and two separate audio tracks -- `rtsp://192.168.1.123:8554/camera1?video&audio=all` - any video codec and all audio codecs as separate tracks -- `http://192.168.1.123:1984/api/stream.m3u8?src=camera1&mp4` - HLS stream with MP4 compatible codecs (HLS/fMP4) -- `http://192.168.1.123:1984/api/stream.m3u8?src=camera1&mp4=flac` - HLS stream with PCMA/PCMU/PCM audio support (HLS/fMP4), won't work on old devices -- `http://192.168.1.123:1984/api/stream.mp4?src=camera1&mp4=flac` - MP4 file with PCMA/PCMU/PCM audio support, won't work on old devices (ex. iOS 12) -- `http://192.168.1.123:1984/api/stream.mp4?src=camera1&mp4=all` - MP4 file with non-standard audio codecs, won't work on some players - -# Codecs madness - -`AVC/H.264` video can be played almost anywhere. But `HEVC/H.265` has many limitations in supporting different devices and browsers. - -| Device | WebRTC | MSE | HTTP* | HLS | -|--------------------------------------------------------------------|-----------------------------------------|-----------------------------------------|----------------------------------------------|-----------------------------| -| *latency* | best | medium | bad | bad | -| Desktop Chrome 136+
Desktop Edge
Android Chrome 136+ | H264, H265*
PCMU, PCMA
OPUS | H264, H265*
AAC, FLAC*
OPUS | H264, H265*
AAC, FLAC*
OPUS, MP3 | no | -| Desktop Firefox | H264
PCMU, PCMA
OPUS | H264
AAC, FLAC*
OPUS | H264
AAC, FLAC*
OPUS | no | -| Desktop Safari 14+
iPad Safari 14+
iPhone Safari 17.1+ | H264, H265*
PCMU, PCMA
OPUS | H264, H265
AAC, FLAC* | **no!** | H264, H265
AAC, FLAC* | -| iPhone Safari 14+ | H264, H265*
PCMU, PCMA
OPUS | **no!** | **no!** | H264, H265
AAC, FLAC* | -| macOS [Hass App][1] | no | no | no | H264, H265
AAC, FLAC* | - -[1]: https://apps.apple.com/app/home-assistant/id1099568401 - -- `HTTP*` - HTTP Progressive Streaming, not related to [progressive download](https://en.wikipedia.org/wiki/Progressive_download), because the file has no size and no end -- `WebRTC H265` - supported in [Chrome 136+](https://developer.chrome.com/release-notes/136), supported in [Safari 18+](https://developer.apple.com/documentation/safari-release-notes/safari-18-release-notes) -- `MSE iPhone` - supported in [iOS 17.1+](https://webkit.org/blog/14735/webkit-features-in-safari-17-1/) - -**Audio** - -- go2rtc supports [automatic repackaging](#built-in-transcoding) of `PCMA/PCMU/PCM` codecs into `FLAC` for MSE/MP4/HLS so they'll work almost anywhere -- **WebRTC** audio codecs: `PCMU/8000`, `PCMA/8000`, `OPUS/48000/2` -- `OPUS` and `MP3` inside **MP4** are part of the standard, but some players do not support them anyway (especially Apple) - -**Apple devices** - -- all Apple devices don't support HTTP progressive streaming -- old iPhone firmwares don't support MSE technology because it competes with the HTTP Live Streaming (HLS) technology, invented by Apple -- HLS is the worst technology for **live** streaming, it still exists only because of iPhones - -**Codec names** - -- H264 = H.264 = AVC (Advanced Video Coding) -- H265 = H.265 = HEVC (High Efficiency Video Coding) -- PCMA = G.711 PCM (A-law) = PCM A-law (`alaw`) -- PCMU = G.711 PCM (µ-law) = PCM mu-law (`mulaw`) -- PCM = L16 = PCM signed 16-bit big-endian (`s16be`) -- AAC = MPEG4-GENERIC -- MP3 = MPEG-1 Audio Layer III or MPEG-2 Audio Layer III - -# Built-in transcoding - -There are no plans to embed complex transcoding algorithms inside go2rtc. [FFmpeg source](#source-ffmpeg) does a great job with this. Including [hardware acceleration](https://github.com/AlexxIT/go2rtc/wiki/Hardware-acceleration) support. - -But go2rtc has some simple algorithms. They are turned on automatically; you do not need to set them up additionally. - -**PCM for MSE/MP4/HLS** - -Go2rtc can pack `PCMA`, `PCMU` and `PCM` codecs into an MP4 container so that they work in all browsers and all built-in players on modern devices. Including Apple QuickTime: - -```text -PCMA/PCMU => PCM => FLAC => MSE/MP4/HLS -``` - -**Resample PCMA/PCMU for WebRTC** - -By default WebRTC supports only `PCMA/8000` and `PCMU/8000`. But go2rtc can automatically resample PCMA and PCMU codecs with a different sample rate. Also, go2rtc can transcode `PCM` codec to `PCMA/8000`, so WebRTC can play it: - -```text -PCM/xxx => PCMA/8000 => WebRTC -PCMA/xxx => PCMA/8000 => WebRTC -PCMU/xxx => PCMU/8000 => WebRTC -``` - -**Important** - -- FLAC codec not supported in an RTSP stream. If you are using Frigate or Home Assistant for recording MP4 files with PCMA/PCMU/PCM audio, you should set up transcoding to the AAC codec. -- PCMA and PCMU are VERY low-quality codecs. They support only 256! different sounds. Use them only when you have no other options. - -# Codecs negotiation - -For example, you want to watch an RTSP stream from a [Dahua IPC-K42](https://www.dahuasecurity.com/fr/products/All-Products/Network-Cameras/Wireless-Series/Wi-Fi-Series/4MP/IPC-K42) camera in your Chrome browser. - -- this camera supports two-way audio standard **ONVIF Profile T** -- this camera supports codecs **H264, H265** for sending video, and you select `H264` in camera settings -- this camera supports codecs **AAC, PCMU, PCMA** for sending audio (from mic), and you select `AAC/16000` in camera settings -- this camera supports codecs **AAC, PCMU, PCMA** for receiving audio (to speaker), you don't need to select them -- your browser supports codecs **H264, VP8, VP9, AV1** for receiving video, you don't need to select them -- your browser supports codecs **OPUS, PCMU, PCMA** for sending and receiving audio, you don't need to select them -- you can't get the camera audio directly because its audio codecs don't match your browser's codecs - - so you decide to use transcoding via FFmpeg and add this setting to the config YAML file - - you have chosen `OPUS/48000/2` codec, because it is higher quality than the `PCMU/8000` or `PCMA/8000` - -Now you have a stream with two sources - **RTSP and FFmpeg**: - -```yaml -streams: - dahua: - - rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0&unicast=true&proto=Onvif - - ffmpeg:rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0#audio=opus -``` - -**go2rtc** automatically matches codecs for your browser across all of your stream sources. This is called **multi-source two-way codec negotiation**, and it's one of the main features of this app. - -![Codec negotiation](assets/codecs.svg) - -**PS.** You can select `PCMU` or `PCMA` codec in camera settings and not use transcoding at all. Or you can select `AAC` codec for main stream and `PCMU` codec for second stream and add both RTSP to YAML config, this also will work fine. - -# Projects using go2rtc +## Projects using go2rtc - [Home Assistant](https://www.home-assistant.io/) [2024.11+](https://www.home-assistant.io/integrations/go2rtc/) - top open-source smart home project - [Frigate](https://frigate.video/) [0.12+](https://docs.frigate.video/guides/configuring_go2rtc/) - open-source NVR built around real-time AI object detection @@ -1450,7 +501,7 @@ streams: - [Synology NAS](https://synocommunity.com/package/go2rtc) - [Unraid](https://unraid.net/community/apps?q=go2rtc) -# Camera experience +## Camera experience - [Dahua](https://www.dahuasecurity.com/) - reference implementation streaming protocols, a lot of settings, high stream quality, multiple streaming clients - [EZVIZ](https://www.ezviz.com/) - awful RTSP protocol implementation, many bugs in SDP @@ -1458,9 +509,9 @@ streams: - [Reolink](https://reolink.com/) - some models have an awful, unusable RTSP implementation and not the best RTMP alternative (I recommend that you contact Reolink support for new firmware), few settings - [Sonoff](https://sonoff.tech/) - very low stream quality, no settings, not the best protocol implementation - [TP-Link](https://www.tp-link.com/) - few streaming clients, packet loss? -- Chinese cheap noname cameras, Wyze Cams, Xiaomi cameras with hacks (usually have `/live/ch00_1` in RTSP URL) - awful but usable RTSP protocol implementation, low stream quality, few settings, packet loss? +- Cheap noname cameras, Wyze Cams, Xiaomi cameras with hacks (usually have `/live/ch00_1` in RTSP URL) - awful but usable RTSP protocol implementation, low stream quality, few settings, packet loss? -# Tips +## Tips **Using apps for low RTSP delay** diff --git a/api/README.md b/api/README.md deleted file mode 100644 index 03b99bc4..00000000 --- a/api/README.md +++ /dev/null @@ -1,117 +0,0 @@ -# API - -Fill free to make any API design proposals. - -## HTTP API - -Interactive [OpenAPI](https://go2rtc.org/api/). - -`www/stream.html` - universal viewer with support params in URL: - -- multiple streams on page `src=camera1&src=camera2...` -- stream technology autoselection `mode=webrtc,webrtc/tcp,mse,hls,mp4,mjpeg` -- stream technology comparison `src=camera1&mode=webrtc&mode=mse&mode=mp4` -- player width setting in pixels `width=320px` or percents `width=50%` - -`www/webrtc.html` - WebRTC viewer with support two way audio and params in URL: - -- `media=video+audio` - simple viewer -- `media=video+audio+microphone` - two way audio from camera -- `media=camera+microphone` - stream from browser -- `media=display+speaker` - stream from desktop - -## JavaScript API - -- You can write your viewer from the scratch -- You can extend the built-in viewer - `www/video-rtc.js` -- Check example - `www/video-stream.js` -- Check example - https://github.com/AlexxIT/WebRTC - -`video-rtc.js` features: - -- support technologies: - - WebRTC over UDP or TCP - - MSE or HLS or MP4 or MJPEG over WebSocket -- automatic selection best technology according on: - - codecs inside your stream - - current browser capabilities - - current network configuration -- automatic stop stream while browser or page not active -- automatic stop stream while player not inside page viewport -- automatic reconnection - -Technology selection based on priorities: - -1. Video and Audio better than just Video -2. H265 better than H264 -3. WebRTC better than MSE, than HLS, than MJPEG - -## WebSocket API - -Endpoint: `/api/ws` - -Query parameters: - -- `src` (required) - Stream name - -### WebRTC - -Request SDP: - -```json -{"type":"webrtc/offer","value":"v=0\r\n..."} -``` - -Response SDP: - -```json -{"type":"webrtc/answer","value":"v=0\r\n..."} -``` - -Request/response candidate: - -- empty value also allowed and optional - -```json -{"type":"webrtc/candidate","value":"candidate:3277516026 1 udp 2130706431 192.168.1.123 54321 typ host"} -``` - -### MSE - -Request: - -- codecs list optional - -```json -{"type":"mse","value":"avc1.640029,avc1.64002A,avc1.640033,hvc1.1.6.L153.B0,mp4a.40.2,mp4a.40.5,flac,opus"} -``` - -Response: - -```json -{"type":"mse","value":"video/mp4; codecs=\"avc1.64001F,mp4a.40.2\""} -``` - -### HLS - -Request: - -```json -{"type":"hls","value":"avc1.640029,avc1.64002A,avc1.640033,hvc1.1.6.L153.B0,mp4a.40.2,mp4a.40.5,flac"} -``` - -Response: - -- you MUST rewrite full HTTP path to `http://192.168.1.123:1984/api/hls/playlist.m3u8` - -```json -{"type":"hls","value":"#EXTM3U\n#EXT-X-STREAM-INF:BANDWIDTH=1000000,CODECS=\"avc1.64001F,mp4a.40.2\"\nhls/playlist.m3u8?id=DvmHdd9w"} -``` - -### MJPEG - -Request/response: - -```json -{"type":"mjpeg"} -``` diff --git a/assets/codecs.svg b/assets/codecs.svg deleted file mode 100644 index 26f5cbd0..00000000 --- a/assets/codecs.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
go2rtc Stream
go2rtc Stream
Consumer: WebRTC (Google Chrome)
Consumer: WebRTC (Google Chrome)
Media: video, recvonly
Media: video, recvonly
Codec: H264
Codec: H264
Codec: VP8
Codec: VP8
Codec: VP9
Codec: VP9
Codec: AV1
Codec: AV1
Media: audio, sendrecv
Media: audio, sendrecv
Codec: OPUS/48000/2
Codec: OPUS/48000/2
Codec: PCMU/8000
Codec: PCMU/8000
Codec: PCMA/8000
Codec: PCMA/8000
Producer: RTSP (IPCam Dahua)
Producer: RTSP (IPCam Dahua)
Media: video, sendonly
Media: video, sendonly
Codec: H264
Codec: H264
Media: audio, sendonly
Media: audio, sendonly
Codec: AAC/16000
Codec: AAC/16000
Media: audio, recvonly
Media: audio, recvonly
Codec: PCMA/8000
Codec: PCMA/8000
Producer: RTSP FFmpeg
Producer: RTSP FFmpeg
Media: audio, sendonly
Media: audio, sendonly
Codec: OPUS/48000/2
Codec: OPUS/48000/2
FFmpeg
FFmpeg
Codec: PCMA/8000
Codec: PCMA/8000Text is not SVG - cannot display \ No newline at end of file diff --git a/docker/README.md b/docker/README.md index b8119efc..c4bd8007 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,3 +1,7 @@ +# Docker + +Images are built automatically via [GitHub actions](https://github.com/AlexxIT/go2rtc/actions) and published on [Docker Hub](https://hub.docker.com/r/alexxit/go2rtc) and [GitHub](https://github.com/AlexxIT/go2rtc/pkgs/container/go2rtc). + ## Versions - `alexxit/go2rtc:latest` - latest release based on `alpine` (`amd64`, `386`, `arm/v6`, `arm/v7`, `arm64`) with support hardware transcoding for Intel iGPU and Raspberry diff --git a/internal/README.md b/internal/README.md new file mode 100644 index 00000000..17a7e69d --- /dev/null +++ b/internal/README.md @@ -0,0 +1,67 @@ +# Modules + +go2rtc tries to name formats, protocols and codecs the same way they are named in FFmpeg. +Some formats and protocols go2rtc supports exclusively. They have no equivalent in FFmpeg. + +- The `echo`, `expr`, `hass` and `onvif` modules receive a link to a stream. They don't know the protocol in advance. +- The `exec` and `ffmpeg` modules support many formats. They are identical to the `http` module. +- The `api`, `app`, `debug`, `ngrok`, `pinggy`, `srtp`, `streams` are supporting modules. + +**Modules** implement communication APIs: authorization, encryption, command set, structure of media packets. + +**Formats** describe the structure of the data being transmitted. + +**Protocols** implement transport for data transmission. + +| module | formats | protocols | input | output | ingest | two-way | +|--------------|-----------------|------------------|-------|--------|--------|---------| +| `alsa` | `pcm` | `ioctl` | yes | | | | +| `bubble` | - | `http` | yes | | | | +| `doorbird` | `mulaw` | `http` | yes | | | yes | +| `dvrip` | - | `tcp` | yes | | | yes | +| `echo` | * | * | yes | | | | +| `eseecloud` | `rtp` | `http` | yes | | | | +| `exec` | * | `pipe`, `rtsp` | yes | | | yes | +| `expr` | * | * | yes | | | | +| `ffmpeg` | * | `pipe`, `rtsp` | yes | | | | +| `flussonic` | `mp4` | `ws` | yes | | | | +| `gopro` | `mpegts` | `udp` | yes | | | | +| `hass` | * | * | yes | | | | +| `hls` | `mpegts`, `mp4` | `http` | | yes | | | +| `homekit` | `rtp` | `hap` | yes | yes | | no | +| `http` | `adts` | `http`, `tcp` | yes | | | | +| `http` | `flv` | `http`, `tcp` | yes | | | | +| `http` | `h264` | `http`, `tcp` | yes | | | | +| `http` | `hevc` | `http`, `tcp` | yes | | | | +| `http` | `hls` | `http`, `tcp` | yes | | | | +| `http` | `mjpeg` | `http`, `tcp` | yes | | | | +| `http` | `mpjpeg` | `http` | yes | | | | +| `http` | `mpegts` | `http`, `tcp` | yes | | | | +| `http` | `wav` | `http`, `tcp` | yes | | | | +| `http` | `yuv4mpegpipe` | `http`, `tcp` | yes | | | | +| `isapi` | `alaw`, `mulaw` | `http` | | | | yes | +| `ivideon` | `mp4` | `ws` | yes | | | | +| `mjpeg` | `ascii` | `http` | | yes | | | +| `mjpeg` | `jpeg` | `http` | | yes | | | +| `mjpeg` | `mpjpeg` | `http` | | yes | yes | | +| `mjpeg` | `yuv4mpegpipe` | `http` | | yes | | | +| `mp4` | `mp4` | `http`, `ws` | | yes | | | +| `mpegts` | `adts` | `http` | | yes | | | +| `mpegts` | `mpegts` | `http` | | yes | yes | | +| `multitrans` | `rtp` | `tcp` | | | | yes | +| `nest` | `srtp` | `rtsp`, `webrtc` | yes | | | no | +| `onvif` | `rtp` | * | yes | yes | | | +| `ring` | `srtp` | `webrtc` | yes | | | yes | +| `roborock` | `srtp` | `webrtc` | yes | | | yes | +| `rtmp` | `rtmp` | `rtmp` | yes | yes | yes | | +| `rtmp` | `flv` | `http` | | yes | yes | | +| `rtsp` | `rtsp` | `rtsp` | yes | yes | yes | yes | +| `tapo` | `mpegts` | `http` | yes | | | yes | +| `tuya` | `srtp` | `webrtc` | yes | | | yes | +| `v4l2` | `rawvideo` | `ioctl` | yes | | | | +| `webrtc` | `srtp` | `webrtc` | yes | yes | yes | yes | +| `webtorrent` | `srtp` | `webrtc` | yes | yes | | | +| `wyoming` | `pcm` | `tcp` | | yes | | | +| `wyze` | - | `tutk` | yes | | | yes | +| `xiaomi` | - | `cs2`, `tutk` | yes | | | yes | +| `yandex` | `srtp` | `webrtc` | yes | | | | diff --git a/internal/alsa/README.md b/internal/alsa/README.md new file mode 100644 index 00000000..3e0b8535 --- /dev/null +++ b/internal/alsa/README.md @@ -0,0 +1,12 @@ +# ALSA + +[`new in v1.9.10`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.10) + +> [!WARNING] +> This source is under development and does not always work well. + +[Advanced Linux Sound Architecture](https://en.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture) - a framework for receiving audio from devices on Linux OS. + +Easy to add via **WebUI > add > ALSA**. + +Alternatively, you can use FFmpeg source. diff --git a/internal/api/README.md b/internal/api/README.md index 4a7d08f1..2e17ff85 100644 --- a/internal/api/README.md +++ b/internal/api/README.md @@ -1,4 +1,45 @@ -## Exit codes +# HTTP API -- https://tldp.org/LDP/abs/html/exitcodes.html -- https://komodor.com/learn/exit-codes-in-containers-and-kubernetes-the-complete-guide/ +The HTTP API is the main part for interacting with the application. Default address: `http://localhost:1984/`. + +The HTTP API is described in [OpenAPI](../../website/api/openapi.yaml) format. It can be explored in [interactive viewer](https://go2rtc.org/api/). WebSocket API described [here](ws/README.md). + +The project's static HTML and JS files are located in the [www](../../www) folder. An external developer can use them as a basis for integrating go2rtc into their project or for developing a custom web interface for go2rtc. + +The contents of `www` folder are built into go2rtc when building, but you can use configuration to specify an external folder as the source of static files. + +## Configuration + +**Important!** go2rtc passes requests from localhost and Unix sockets without HTTP authorization, even if you have it configured. It is your responsibility to set up secure external access to the API. If not properly configured, an attacker can gain access to your cameras and even your server. + +- you can disable HTTP API with `listen: ""` and use, for example, only RTSP client/server protocol +- you can enable HTTP API only on localhost with `listen: "127.0.0.1:1984"` setting +- you can change the API `base_path` and host go2rtc on your main app webserver suburl +- all files from `static_dir` hosted on root path: `/` +- you can use raw TLS cert/key content or path to files + +```yaml +api: + listen: ":1984" # default ":1984", HTTP API port ("" - disabled) + username: "admin" # default "", Basic auth for WebUI + password: "pass" # default "", Basic auth for WebUI + local_auth: true # default false, Enable auth check for localhost requests + base_path: "/rtc" # default "", API prefix for serving on suburl (/api => /rtc/api) + static_dir: "www" # default "", folder for static files (custom web interface) + origin: "*" # default "", allow CORS requests (only * supported) + tls_listen: ":443" # default "", enable HTTPS server + tls_cert: | # default "", PEM-encoded fullchain certificate for HTTPS + -----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE----- + tls_key: | # default "", PEM-encoded private key for HTTPS + -----BEGIN PRIVATE KEY----- + ... + -----END PRIVATE KEY----- + unix_listen: "/tmp/go2rtc.sock" # default "", unix socket listener for API +``` + +**PS:** + +- MJPEG over WebSocket plays better than native MJPEG because Chrome [bug](https://bugs.chromium.org/p/chromium/issues/detail?id=527446) +- MP4 over WebSocket was created only for Apple iOS because it doesn't support file streaming diff --git a/internal/api/ws/README.md b/internal/api/ws/README.md new file mode 100644 index 00000000..5599ff88 --- /dev/null +++ b/internal/api/ws/README.md @@ -0,0 +1,69 @@ +# WebSocket + +Endpoint: `/api/ws` + +Query parameters: + +- `src` (required) - Stream name + +### WebRTC + +Request SDP: + +```json +{"type":"webrtc/offer","value":"v=0\r\n..."} +``` + +Response SDP: + +```json +{"type":"webrtc/answer","value":"v=0\r\n..."} +``` + +Request/response candidate: + +- empty value also allowed and optional + +```json +{"type":"webrtc/candidate","value":"candidate:3277516026 1 udp 2130706431 192.168.1.123 54321 typ host"} +``` + +### MSE + +Request: + +- codecs list optional + +```json +{"type":"mse","value":"avc1.640029,avc1.64002A,avc1.640033,hvc1.1.6.L153.B0,mp4a.40.2,mp4a.40.5,flac,opus"} +``` + +Response: + +```json +{"type":"mse","value":"video/mp4; codecs=\"avc1.64001F,mp4a.40.2\""} +``` + +### HLS + +Request: + +```json +{"type":"hls","value":"avc1.640029,avc1.64002A,avc1.640033,hvc1.1.6.L153.B0,mp4a.40.2,mp4a.40.5,flac"} +``` + +Response: + +- you MUST rewrite full HTTP path to `http://192.168.1.123:1984/api/hls/playlist.m3u8` + +```json +{"type":"hls","value":"#EXTM3U\n#EXT-X-STREAM-INF:BANDWIDTH=1000000,CODECS=\"avc1.64001F,mp4a.40.2\"\nhls/playlist.m3u8?id=DvmHdd9w"} +``` + +### MJPEG + +Request/response: + +```json +{"type":"mjpeg"} +``` diff --git a/internal/app/README.md b/internal/app/README.md index f7e1e1b9..aa3b96cf 100644 --- a/internal/app/README.md +++ b/internal/app/README.md @@ -1,3 +1,9 @@ +# App + +The application module is responsible for reading configuration files and running other modules. + +The configuration can be edited through the application's WebUI with code highlighting, syntax and specification checking. + - By default, go2rtc will search for the `go2rtc.yaml` config file in the current working directory - go2rtc supports multiple config files: - `go2rtc -c config1.yaml -c config2.yaml -c config3.yaml` @@ -38,6 +44,12 @@ Editors like [GoLand](https://www.jetbrains.com/go/) and [VS Code](https://code. # yaml-language-server: $schema=https://raw.githubusercontent.com/AlexxIT/go2rtc/master/www/schema.json ``` +or from a running go2rtc: + +```yaml +# yaml-language-server: $schema=http://localhost:1984/schema.json +``` + ## Defaults - Default values may change in updates @@ -45,26 +57,41 @@ Editors like [GoLand](https://www.jetbrains.com/go/) and [VS Code](https://code. ```yaml api: - listen: ":1984" + listen: ":1984" # default public port for WebUI and HTTP API ffmpeg: - bin: "ffmpeg" + bin: "ffmpeg" # default binary path for FFmpeg log: - format: "color" - level: "info" + level: "info" # default log level output: "stdout" time: "UNIXMS" rtsp: - listen: ":8554" + listen: ":8554" # default public port for RTSP server default_query: "video&audio" srtp: - listen: ":8443" + listen: ":8443" # default public port for SRTP server (used for HomeKit) webrtc: - listen: ":8555/tcp" + listen: ":8555" # default public port for WebRTC server (TCP and UDP) ice_servers: - - urls: [ "stun:stun.l.google.com:19302" ] + - urls: [ "stun:stun.cloudflare.com:3478", "stun:stun.l.google.com:19302" ] ``` + +## Log + +You can set different log levels for different modules. + +```yaml +log: + format: "" # empty (default, autodetect color support), color, json, text + level: "info" # disabled, trace, debug, info (default), warn, error + output: "stdout" # empty (only to memory), stderr, stdout (default) + time: "UNIXMS" # empty (disable timestamp), UNIXMS (default), UNIXMICRO, UNIXNANO + + api: trace # module name: log level +``` + +Modules: `api`, `streams`, `rtsp`, `webrtc`, `mp4`, `hls`, `mjpeg`, `hass`, `homekit`, `onvif`, `rtmp`, `webtorrent`, `wyoming`, `echo`, `exec`, `expr`, `ffmpeg`, `wyze`, `xiaomi`. diff --git a/internal/bubble/README.md b/internal/bubble/README.md new file mode 100644 index 00000000..30ebad97 --- /dev/null +++ b/internal/bubble/README.md @@ -0,0 +1,15 @@ +# Bubble + +[`new in v1.6.1`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.6.1) + +Private format in some cameras from [dvr163.com](http://help.dvr163.com/) and [eseecloud.com](http://www.eseecloud.com/). + +## Configuration + +- you can skip `username`, `password`, `port`, `ch` and `stream` if they are default +- set up separate streams for different channels and streams + +```yaml +streams: + camera1: bubble://username:password@192.168.1.123:34567/bubble/live?ch=0&stream=0 +``` diff --git a/internal/debug/README.md b/internal/debug/README.md new file mode 100644 index 00000000..e03b2f82 --- /dev/null +++ b/internal/debug/README.md @@ -0,0 +1,3 @@ +# Debug + +This module provides `GET /api/stack`, with which you can find hanging goroutines diff --git a/internal/doorbird/README.md b/internal/doorbird/README.md index 7c31efae..78e67a42 100644 --- a/internal/doorbird/README.md +++ b/internal/doorbird/README.md @@ -1,6 +1,6 @@ # Doorbird -*[added in v1.9.8](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.11)* +[`new in v1.9.8`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.8) This source type supports [Doorbird](https://www.doorbird.com/) devices including MJPEG stream, audio stream as well as two-way audio. diff --git a/internal/dvrip/README.md b/internal/dvrip/README.md new file mode 100644 index 00000000..792834ca --- /dev/null +++ b/internal/dvrip/README.md @@ -0,0 +1,21 @@ +# DVR-IP + +[`new in v1.2.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.2.0) + +Private format from DVR-IP NVR, NetSurveillance, Sofia protocol (NETsurveillance ActiveX plugin XMeye SDK). + +## Configuration + +- you can skip `username`, `password`, `port`, `channel` and `subtype` if they are default +- set up separate streams for different channels +- use `subtype=0` for Main stream, and `subtype=1` for Extra1 stream +- only the TCP protocol is supported + +```yaml +streams: + only_stream: dvrip://username:password@192.168.1.123:34567?channel=0&subtype=0 + only_tts: dvrip://username:password@192.168.1.123:34567?backchannel=1 + two_way_audio: + - dvrip://username:password@192.168.1.123:34567?channel=0&subtype=0 + - dvrip://username:password@192.168.1.123:34567?backchannel=1 +``` diff --git a/internal/echo/README.md b/internal/echo/README.md new file mode 100644 index 00000000..4ef3579c --- /dev/null +++ b/internal/echo/README.md @@ -0,0 +1,48 @@ +# Echo + +Some sources may have a dynamic link. And you will need to get it using a Bash or Python script. Your script should echo a link to the source. RTSP, FFmpeg or any of the supported sources. + +**Docker** and **Home Assistant add-on** users has preinstalled `python3`, `curl`, `jq`. + +## Configuration + +```yaml +streams: + apple_hls: echo:python3 hls.py https://developer.apple.com/streaming/examples/basic-stream-osx-ios5.html +``` + +## Install python libraries + +**Docker** and **Hass Add-on** users has preinstalled `python3` without any additional libraries, like [requests](https://requests.readthedocs.io/) or others. If you need some additional libraries - you need to install them to folder with your script: + +1. Install [SSH & Web Terminal](https://github.com/hassio-addons/addon-ssh) +2. Goto Add-on Web UI +3. Install library: `pip install requests -t /config/echo` +4. Add your script to `/config/echo/myscript.py` +5. Use your script as source `echo:python3 /config/echo/myscript.py` + +## Example: Apple HLS + +```yaml +streams: + apple_hls: echo:python3 hls.py https://developer.apple.com/streaming/examples/basic-stream-osx-ios5.html +``` + +**hls.py** + +```python +import re +import sys +from urllib.parse import urljoin +from urllib.request import urlopen + +html = urlopen(sys.argv[1]).read().decode("utf-8") +url = re.search(r"https.+?m3u8", html)[0] + +html = urlopen(url).read().decode("utf-8") +m = re.search(r"^[a-z0-1/_]+\.m3u8$", html, flags=re.MULTILINE) +url = urljoin(url, m[0]) + +# ffmpeg:https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_16x9/gear1/prog_index.m3u8#video=copy +print("ffmpeg:" + url + "#video=copy") +``` diff --git a/internal/eseecloud/README.md b/internal/eseecloud/README.md new file mode 100644 index 00000000..30db8409 --- /dev/null +++ b/internal/eseecloud/README.md @@ -0,0 +1,12 @@ +# EseeCloud + +[`new in v1.9.10`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.10) + +This source is for cameras with a link like this `http://admin:@192.168.1.123:80/livestream/12`. Related [issue](https://github.com/AlexxIT/go2rtc/issues/1690). + +## Configuration + +```yaml +streams: + camera1: eseecloud://user:pass@192.168.1.123:80/livestream/12 +``` diff --git a/internal/exec/README.md b/internal/exec/README.md index e15a9657..43dad3c5 100644 --- a/internal/exec/README.md +++ b/internal/exec/README.md @@ -1,3 +1,39 @@ +# Exec + +Exec source can run any external application and expect data from it. Two transports are supported - **pipe** ([`new in v1.5.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.5.0)) and **RTSP**. + +If you want to use **RTSP** transport, the command must contain the `{output}` argument in any place. On launch, it will be replaced by the local address of the RTSP server. + +**pipe** reads data from app stdout in different formats: **MJPEG**, **H.264/H.265 bitstream**, **MPEG-TS**. Also pipe can write data to app stdin in two formats: **PCMA** and **PCM/48000**. + +The source can be used with: + +- [FFmpeg](https://ffmpeg.org/) - go2rtc ffmpeg source just a shortcut to exec source +- [FFplay](https://ffmpeg.org/ffplay.html) - play audio on your server +- [GStreamer](https://gstreamer.freedesktop.org/) +- [Raspberry Pi Cameras](https://www.raspberrypi.com/documentation/computers/camera_software.html) +- any of your own software + +## Configuration + +Pipe commands support parameters (format: `exec:{command}#{param1}#{param2}`): + +- `killsignal` - signal which will be sent to stop the process (numeric form) +- `killtimeout` - time in seconds for forced termination with sigkill +- `backchannel` - enable backchannel for two-way audio +- `starttimeout` - time in seconds for waiting first byte from RTSP + +```yaml +streams: + stream: exec:ffmpeg -re -i /media/BigBuckBunny.mp4 -c copy -rtsp_transport tcp -f rtsp {output} + picam_h264: exec:libcamera-vid -t 0 --inline -o - + picam_mjpeg: exec:libcamera-vid -t 0 --codec mjpeg -o - + pi5cam_h264: exec:libcamera-vid -t 0 --libav-format h264 -o - + canon: exec:gphoto2 --capture-movie --stdout#killsignal=2#killtimeout=5 + play_pcma: exec:ffplay -fflags nobuffer -f alaw -ar 8000 -i -#backchannel=1 + play_pcm48k: exec:ffplay -fflags nobuffer -f s16be -ar 48000 -i -#backchannel=1 +``` + ## Backchannel - You can check audio card names in the **Go2rtc > WebUI > Add** diff --git a/internal/expr/README.md b/internal/expr/README.md index 2ad005ce..424f4d0f 100644 --- a/internal/expr/README.md +++ b/internal/expr/README.md @@ -1,5 +1,7 @@ # Expr +[`new in v1.8.2`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.8.2) + [Expr](https://github.com/antonmedv/expr) - expression language and expression evaluation for Go. - [language definition](https://expr.medv.io/docs/Language-Definition) - takes best from JS, Python, Jinja2 syntax diff --git a/internal/ffmpeg/README.md b/internal/ffmpeg/README.md index 46419975..03f29215 100644 --- a/internal/ffmpeg/README.md +++ b/internal/ffmpeg/README.md @@ -1,70 +1,62 @@ -# ffmpeg +# FFmpeg -## FFplay output +You can get any stream, file or device via FFmpeg and push it to go2rtc. The app will automatically start FFmpeg with the proper arguments when someone starts watching the stream. -[FFplay](https://stackoverflow.com/questions/27778678/what-are-mv-fd-aq-vq-sq-and-f-in-a-video-stream) `7.11 A-V: 0.003 fd= 1 aq= 21KB vq= 321KB sq= 0B f=0/0`: +- FFmpeg preinstalled for **Docker** and **Home Assistant add-on** users +- **Home Assistant add-on** users can target files from [/media](https://www.home-assistant.io/more-info/local-media/setup-media/) folder -- `7.11` - master clock, is the time from start of the stream/video -- `A-V` - av_diff, difference between audio and video timestamps -- `fd` - frames dropped -- `aq` - audio queue (0 - no delay) -- `vq` - video queue (0 - no delay) -- `sq` - subtitle queue -- `f` - timestamp error correction rate (Not 100% sure) +## Configuration -`M-V`, `M-A` means video stream only, audio stream only respectively. - -## Devices Windows - -``` ->ffmpeg -hide_banner -f dshow -list_options true -i video="VMware Virtual USB Video Device" -[dshow @ 0000025695e52900] DirectShow video device options (from video devices) -[dshow @ 0000025695e52900] Pin "Record" (alternative pin name "0") -[dshow @ 0000025695e52900] pixel_format=yuyv422 min s=1280x720 fps=1 max s=1280x720 fps=10 -[dshow @ 0000025695e52900] pixel_format=yuyv422 min s=1280x720 fps=1 max s=1280x720 fps=10 (tv, bt470bg/bt709/unknown, topleft) -[dshow @ 0000025695e52900] pixel_format=nv12 min s=1280x720 fps=1 max s=1280x720 fps=23 -[dshow @ 0000025695e52900] pixel_format=nv12 min s=1280x720 fps=1 max s=1280x720 fps=23 (tv, bt470bg/bt709/unknown, topleft) -``` - -## Devices Mac - -``` -% ./ffmpeg -hide_banner -f avfoundation -list_devices true -i "" -[AVFoundation indev @ 0x7f8b1f504d80] AVFoundation video devices: -[AVFoundation indev @ 0x7f8b1f504d80] [0] FaceTime HD Camera -[AVFoundation indev @ 0x7f8b1f504d80] [1] Capture screen 0 -[AVFoundation indev @ 0x7f8b1f504d80] AVFoundation audio devices: -[AVFoundation indev @ 0x7f8b1f504d80] [0] Soundflower (2ch) -[AVFoundation indev @ 0x7f8b1f504d80] [1] Built-in Microphone -[AVFoundation indev @ 0x7f8b1f504d80] [2] Soundflower (64ch) -``` - -## Devices Linux - -``` -# ffmpeg -hide_banner -f v4l2 -list_formats all -i /dev/video0 -[video4linux2,v4l2 @ 0x7f7de7c58bc0] Raw : yuyv422 : YUYV 4:2:2 : 640x480 160x120 176x144 320x176 320x240 352x288 432x240 544x288 640x360 752x416 800x448 800x600 864x480 960x544 960x720 1024x576 1184x656 1280x720 1280x960 -[video4linux2,v4l2 @ 0x7f7de7c58bc0] Compressed: mjpeg : Motion-JPEG : 640x480 160x120 176x144 320x176 320x240 352x288 432x240 544x288 640x360 752x416 800x448 800x600 864x480 960x544 960x720 1024x576 1184x656 1280x720 1280x960 -``` - -## TTS +Format: `ffmpeg:{input}#{param1}#{param2}#{param3}`. Examples: ```yaml streams: - tts: ffmpeg:#input=-readrate 1 -readrate_initial_burst 0.001 -f lavfi -i "flite=text='1 2 3 4 5 6 7 8 9 0'"#audio=pcma + # [FILE] all tracks will be copied without transcoding codecs + file1: ffmpeg:/media/BigBuckBunny.mp4 + + # [FILE] video will be transcoded to H264, audio will be skipped + file2: ffmpeg:/media/BigBuckBunny.mp4#video=h264 + + # [FILE] video will be copied, audio will be transcoded to PCMU + file3: ffmpeg:/media/BigBuckBunny.mp4#video=copy#audio=pcmu + + # [HLS] video will be copied, audio will be skipped + hls: ffmpeg:https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_16x9/gear5/prog_index.m3u8#video=copy + + # [MJPEG] video will be transcoded to H264 + mjpeg: ffmpeg:http://185.97.122.128/cgi-bin/faststream.jpg#video=h264 + + # [RTSP] video with rotation, should be transcoded, so select H264 + rotate: ffmpeg:rtsp://12345678@192.168.1.123/av_stream/ch0#video=h264#rotate=90 ``` -## Useful links +All transcoding formats have [built-in templates](ffmpeg.go): `h264`, `h265`, `opus`, `pcmu`, `pcmu/16000`, `pcmu/48000`, `pcma`, `pcma/16000`, `pcma/48000`, `aac`, `aac/16000`. -- https://superuser.com/questions/564402/explanation-of-x264-tune -- https://stackoverflow.com/questions/33624016/why-sliced-thread-affect-so-much-on-realtime-encoding-using-ffmpeg-x264 -- https://codec.fandom.com/ru/wiki/X264_-_описание_ключей_кодирования -- https://html5test.com/ -- https://trac.ffmpeg.org/wiki/Capture/Webcam -- https://trac.ffmpeg.org/wiki/DirectShow -- https://stackoverflow.com/questions/53207692/libav-mjpeg-encoding-and-huffman-table -- https://github.com/tuupola/esp_video/blob/master/README.md -- https://github.com/leandromoreira/ffmpeg-libav-tutorial -- https://www.reddit.com/user/VeritablePornocopium/comments/okw130/ffmpeg_with_libfdk_aac_for_windows_x64/ -- https://slhck.info/video/2017/02/24/vbr-settings.html -- [HomeKit audio samples problem](https://superuser.com/questions/1290996/non-monotonous-dts-with-igndts-flag) +But you can override them via YAML config. You can also add your own formats to the config and use them with source params. + +```yaml +ffmpeg: + bin: ffmpeg # path to ffmpeg binary + global: "-hide_banner" + timeout: 5 # default timeout in seconds for rtsp inputs + h264: "-codec:v libx264 -g:v 30 -preset:v superfast -tune:v zerolatency -profile:v main -level:v 4.1" + mycodec: "-any args that supported by ffmpeg..." + myinput: "-fflags nobuffer -flags low_delay -timeout {timeout} -i {input}" + myraw: "-ss 00:00:20" +``` + +- You can use go2rtc stream name as ffmpeg input (ex. `ffmpeg:camera1#video=h264`) +- You can use `video` and `audio` params multiple times (ex. `#video=copy#audio=copy#audio=pcmu`) +- You can use `rotate` param with `90`, `180`, `270` or `-90` values, important with transcoding (ex. `#video=h264#rotate=90`) +- You can use `width` and/or `height` params, important with transcoding (ex. `#video=h264#width=1280`) +- You can use `drawtext` to add a timestamp (ex. `drawtext=x=2:y=2:fontsize=12:fontcolor=white:box=1:boxcolor=black`) + - This will greatly increase the CPU of the server, even with hardware acceleration +- You can use `timeout` param to set RTSP input timeout in seconds (ex. `#timeout=10`) +- You can use `raw` param for any additional FFmpeg arguments (ex. `#raw=-vf transpose=1`) +- You can use `input` param to override default input template (ex. `#input=rtsp/udp` will change RTSP transport from TCP to UDP+TCP) + - You can use raw input value (ex. `#input=-timeout {timeout} -i {input}`) + - You can add your own input templates + +Read more about [hardware acceleration](hardware/README.md). + +**PS.** It is recommended to check the available hardware in the WebUI add page. diff --git a/internal/ffmpeg/device/README.md b/internal/ffmpeg/device/README.md new file mode 100644 index 00000000..0188b6fe --- /dev/null +++ b/internal/ffmpeg/device/README.md @@ -0,0 +1,22 @@ +# FFmpeg Device + +You can get video from any USB camera or Webcam as RTSP or WebRTC stream. This is part of FFmpeg integration. + +- check available devices in web interface +- `video_size` and `framerate` must be supported by your camera! +- for Linux supported only video for now +- for macOS you can stream FaceTime camera or whole desktop! +- for macOS important to set right framerate + +## Configuration + +Format: `ffmpeg:device?{input-params}#{param1}#{param2}#{param3}` + +```yaml +streams: + linux_usbcam: ffmpeg:device?video=0&video_size=1280x720#video=h264 + windows_webcam: ffmpeg:device?video=0#video=h264 + macos_facetime: ffmpeg:device?video=0&audio=1&video_size=1280x720&framerate=30#video=h264#audio=pcma +``` + +**PS.** It is recommended to check the available devices in the WebUI add page. diff --git a/internal/flussonic/README.md b/internal/flussonic/README.md new file mode 100644 index 00000000..17455fa7 --- /dev/null +++ b/internal/flussonic/README.md @@ -0,0 +1,5 @@ +# Flussonic + +[`new in v1.9.10`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.10) + +Support streams from [Flusonic](https://flussonic.com/) server. Related [issue](https://github.com/AlexxIT/go2rtc/issues/1678). diff --git a/internal/gopro/README.md b/internal/gopro/README.md index 3b857b1b..d55e31e4 100644 --- a/internal/gopro/README.md +++ b/internal/gopro/README.md @@ -1,11 +1,15 @@ # GoPro +[`new in v1.8.3`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.8.3) + +Support streaming from [GoPro](https://gopro.com/) cameras, connected via USB or Wi-Fi to Linux, Mac, Windows. + Supported models: HERO9, HERO10, HERO11, HERO12. Supported OS: Linux, Mac, Windows, [HassOS](https://www.home-assistant.io/installation/) Other camera models have different APIs. I will try to add them in future versions. -## Config +## Configuration - USB-connected cameras create a new network interface in the system - Linux users do not need to install anything diff --git a/internal/hass/README.md b/internal/hass/README.md new file mode 100644 index 00000000..9b79b49c --- /dev/null +++ b/internal/hass/README.md @@ -0,0 +1,41 @@ +# Hass + +Support import camera links from [Home Assistant](https://www.home-assistant.io/) config files: + +- [Generic Camera](https://www.home-assistant.io/integrations/generic/), setup via GUI +- [HomeKit Camera](https://www.home-assistant.io/integrations/homekit_controller/) +- [ONVIF](https://www.home-assistant.io/integrations/onvif/) +- [Roborock](https://github.com/humbertogontijo/homeassistant-roborock) vacuums with camera + +## Configuration + +```yaml +hass: + config: "/config" # skip this setting if you are a Home Assistant add-on user + +streams: + generic_camera: hass:Camera1 # Settings > Integrations > Integration Name + aqara_g3: hass:Camera-Hub-G3-AB12 +``` + +### WebRTC Cameras + +[`new in v1.6.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.6.0) + +Any cameras in WebRTC format are supported. But at the moment Home Assistant only supports some [Nest](https://www.home-assistant.io/integrations/nest/) cameras in this format. + +**Important.** The Nest API only allows you to get a link to a stream for 5 minutes. +Do not use this with Frigate! If the stream expires, Frigate will consume all available RAM on your machine within seconds. +It's recommended to use [Nest source](../nest/README.md) - it supports extending the stream. + +```yaml +streams: + # link to Home Assistant Supervised + hass-webrtc1: hass://supervisor?entity_id=camera.nest_doorbell + # link to external Home Assistant with Long-Lived Access Tokens + hass-webrtc2: hass://192.168.1.123:8123?entity_id=camera.nest_doorbell&token=eyXYZ... +``` + +### RTSP Cameras + +By default, the Home Assistant API does not allow you to get a dynamic RTSP link to a camera stream. [This method](https://github.com/felipecrs/hass-expose-camera-stream-source#importing-cameras-from-home-assistant-to-go2rtc-or-frigate) can work around it. diff --git a/internal/hls/README.md b/internal/hls/README.md index c14f0fdb..64471bd4 100644 --- a/internal/hls/README.md +++ b/internal/hls/README.md @@ -1,3 +1,19 @@ +# HLS + +[`new in v1.1.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.1.0) + +[HLS](https://en.wikipedia.org/wiki/HTTP_Live_Streaming) is the worst technology for real-time streaming. +It can only be useful on devices that do not support more modern technology, like [WebRTC](../webrtc/README.md), [MP4](../mp4/README.md). + +The go2rtc implementation differs from the standards and may not work with all players. + +API examples: + +- HLS/TS stream: `http://192.168.1.123:1984/api/stream.m3u8?src=camera1` (H264) +- HLS/fMP4 stream: `http://192.168.1.123:1984/api/stream.m3u8?src=camera1&mp4` (H264, H265, AAC) + +Read more about [codecs filters](../../README.md#codecs-filters). + ## Useful links - https://walterebert.com/playground/video/hls/ diff --git a/internal/homekit/README.md b/internal/homekit/README.md new file mode 100644 index 00000000..a8802fce --- /dev/null +++ b/internal/homekit/README.md @@ -0,0 +1,97 @@ +# Apple HomeKit + +This module supports both client and server for the [Apple HomeKit](https://www.apple.com/home-app/accessories/) protocol. + +## HomeKit Client + +**Important:** + +- You can use HomeKit Cameras **without Apple devices** (iPhone, iPad, etc.), it's just a yet another protocol +- HomeKit device can be paired with only one ecosystem. So, if you have paired it to an iPhone (Apple Home), you can't pair it with Home Assistant or go2rtc. Or if you have paired it to go2rtc, you can't pair it with an iPhone +- HomeKit device should be on the same network with working [mDNS](https://en.wikipedia.org/wiki/Multicast_DNS) between the device and go2rtc + +go2rtc supports importing paired HomeKit devices from [Home Assistant](../hass/README.md). +So you can use HomeKit camera with Home Assistant and go2rtc simultaneously. +If you are using Home Assistant, I recommend pairing devices with it; it will give you more options. + +You can pair device with go2rtc on the HomeKit page. If you can't see your devices, reload the page. +Also, try rebooting your HomeKit device (power off). If you still can't see it, you have a problem with mDNS. + +If you see a device but it does not have a pairing button, it is paired to some ecosystem (Apple Home, Home Assistant, HomeBridge, etc.). You need to delete the device from that ecosystem, and it will be available for pairing. If you cannot unpair the device, you will have to reset it. + +**Important:** + +- HomeKit audio uses very non-standard **AAC-ELD** codec with very non-standard params and specification violations +- Audio can't be played in `VLC` and probably any other player +- Audio should be transcoded for use with MSE, WebRTC, etc. + +### Client Configuration + +Recommended settings for using HomeKit Camera with WebRTC, MSE, MP4, RTSP: + +```yaml +streams: + aqara_g3: + - hass:Camera-Hub-G3-AB12 + - ffmpeg:aqara_g3#audio=aac#audio=opus +``` + +RTSP link with "normal" audio for any player: `rtsp://192.168.1.123:8554/aqara_g3?video&audio=aac` + +**This source is in active development!** Tested only with [Aqara Camera Hub G3](https://www.aqara.com/eu/product/camera-hub-g3) (both EU and CN versions). + +## HomeKit Server + +[`new in v1.7.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.7.0) + +HomeKit module can work in two modes: + +- export any H264 camera to Apple HomeKit +- transparent proxy any Apple HomeKit camera (Aqara, Eve, Eufy, etc.) back to Apple HomeKit, so you will have all camera features in Apple Home and also will have RTSP/WebRTC/MP4/etc. from your HomeKit camera + +**Important** + +- HomeKit cameras support only H264 video and OPUS audio + +### Server Configuration + +**Minimal config** + +```yaml +streams: + dahua1: rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0 +homekit: + dahua1: # same stream ID from streams list, default PIN - 19550224 +``` + +**Full config** + +```yaml +streams: + dahua1: + - rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0 + - ffmpeg:dahua1#video=h264#hardware # if your camera doesn't support H264, important for HomeKit + - ffmpeg:dahua1#audio=opus # only OPUS audio supported by HomeKit + +homekit: + dahua1: # same stream ID from streams list + pin: 12345678 # custom PIN, default: 19550224 + name: Dahua camera # custom camera name, default: generated from stream ID + device_id: dahua1 # custom ID, default: generated from stream ID + device_private: dahua1 # custom key, default: generated from stream ID +``` + +**Proxy HomeKit camera** + +- Video stream from HomeKit camera to Apple device (iPhone, AppleTV) will be transmitted directly +- Video stream from HomeKit camera to RTSP/WebRTC/MP4/etc. will be transmitted via go2rtc + +```yaml +streams: + aqara1: + - homekit://... + - ffmpeg:aqara1#audio=aac#audio=opus # optional audio transcoding + +homekit: + aqara1: # same stream ID from streams list +``` diff --git a/internal/http/README.md b/internal/http/README.md new file mode 100644 index 00000000..b8147b62 --- /dev/null +++ b/internal/http/README.md @@ -0,0 +1,47 @@ +# HTTP + +This source supports receiving a stream via an HTTP link. + +It can determine the source format from the`Content-Type` HTTP header: + +- **HTTP-JPEG** (`image/jpeg`) - camera snapshot link, can be converted by go2rtc to MJPEG stream +- **HTTP-MJPEG** (`multipart/x-mixed-replace`) - A continuous sequence of JPEG frames (with HTTP headers). +- **HLS** (`application/vnd.apple.mpegurl`) - A popular [HTTP Live Streaming](https://en.wikipedia.org/wiki/HTTP_Live_Streaming) (HLS) format, which is not designed for real-time media transmission. + +> [!WARNING] +> The HLS format is not designed for real time and is supported quite poorly. It is recommended to use it via ffmpeg source with buffering enabled (disabled by default). + +## TCP + +Source also supports HTTP and TCP streams with autodetection for different formats: + +- `adts` - Audio stream in [AAC](https://en.wikipedia.org/wiki/Advanced_Audio_Coding) codec with Audio Data Transport Stream (ADTS) headers. +- `flv` - The legacy but still used [Flash Video](https://en.wikipedia.org/wiki/Flash_Video) format. +- `h264` - AVC/H.264 bitstream. +- `hevc` - HEVC/H.265 bitstream. +- `mjpeg` - A continuous sequence of JPEG frames (without HTTP headers). +- `mpegts` - The legacy [MPEG transport stream](https://en.wikipedia.org/wiki/MPEG_transport_stream) format. +- `wav` - Audio stream in [WAV](https://en.wikipedia.org/wiki/WAV) format. +- `yuv4mpegpipe` - Raw YUV frame stream with YUV4MPEG header. + +## Configuration + +```yaml +streams: + # [HTTP-FLV] stream in video/x-flv format + http_flv: http://192.168.1.123:20880/api/camera/stream/780900131155/657617 + + # [JPEG] snapshots from Dahua camera, will be converted to MJPEG stream + dahua_snap: http://admin:password@192.168.1.123/cgi-bin/snapshot.cgi?channel=1 + + # [MJPEG] stream will be proxied without modification + http_mjpeg: https://mjpeg.sanford.io/count.mjpeg + + # [MJPEG or H.264/H.265 bitstream or MPEG-TS] + tcp_magic: tcp://192.168.1.123:12345 + + # Add custom header + custom_header: "https://mjpeg.sanford.io/count.mjpeg#header=Authorization: Bearer XXX" +``` + +**PS.** Dahua camera has a bug: if you select MJPEG codec for RTSP second stream, snapshot won't work. diff --git a/internal/isapi/README.md b/internal/isapi/README.md new file mode 100644 index 00000000..63892f72 --- /dev/null +++ b/internal/isapi/README.md @@ -0,0 +1,14 @@ +# Hikvision ISAPI + +[`new in v1.3.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0) + +This source type supports only backchannel audio for the [Hikvision ISAPI](https://tpp.hikvision.com/download/ISAPI_OTAP) protocol. So it should be used as a second source in addition to the RTSP protocol. + +## Configuration + +```yaml +streams: + hikvision1: + - rtsp://admin:password@192.168.1.123:554/Streaming/Channels/101 + - isapi://admin:password@192.168.1.123:80/ +``` diff --git a/internal/ivideon/README.md b/internal/ivideon/README.md new file mode 100644 index 00000000..9974d0d8 --- /dev/null +++ b/internal/ivideon/README.md @@ -0,0 +1,10 @@ +# Ivideon + +Support public cameras from the service [Ivideon](https://tv.ivideon.com/). + +## Configuration + +```yaml +streams: + quailcam: ivideon:100-tu5dkUPct39cTp9oNEN2B6/0 +``` diff --git a/internal/mjpeg/README.md b/internal/mjpeg/README.md index 4cb4947d..4258c41b 100644 --- a/internal/mjpeg/README.md +++ b/internal/mjpeg/README.md @@ -1,13 +1,19 @@ -# MJPEG +# Motion JPEG + +- This module can provide and receive streams in MJPEG format. +- This module is also responsible for receiving snapshots in JPEG format. +- This module also supports streaming to the server console (terminal) in the **animated ASCII art** format. + +## MJPEG Client **Important.** For a stream in MJPEG format, your source MUST contain the MJPEG codec. If your stream has the MJPEG codec, you can receive an **MJPEG stream** or **JPEG snapshots** via the API. You can receive an MJPEG stream in several ways: -- some cameras support MJPEG codec inside [RTSP stream](#source-rtsp) (ex. second stream for Dahua cameras) -- some cameras have an HTTP link with [MJPEG stream](#source-http) -- some cameras have an HTTP link with snapshots - go2rtc can convert them to [MJPEG stream](#source-http) -- you can convert an H264/H265 stream from your camera via [FFmpeg integration](#source-ffmpeg) +- some cameras support MJPEG codec inside [RTSP stream](../rtsp/README.md) (ex. second stream for Dahua cameras) +- some cameras have an HTTP link with [MJPEG stream](../http/README.md) +- some cameras have an HTTP link with snapshots - go2rtc can convert them to [MJPEG stream](../http/README.md) +- you can convert an H264/H265 stream from your camera via [FFmpeg integration](../ffmpeg/README.md) With this example, your stream will have both H264 and MJPEG codecs: @@ -18,18 +24,22 @@ streams: - ffmpeg:camera1#video=mjpeg ``` -## API examples +## MJPEG Server -**MJPEG stream** +### mpjpeg + +Output a stream in [MJPEG](https://en.wikipedia.org/wiki/Motion_JPEG) format. In [FFmpeg](https://ffmpeg.org/), this format is called `mpjpeg` because it contains HTTP headers. ``` -http://192.168.1.123:1984/api/stream.mjpeg?src=camera1 +ffplay http://192.168.1.123:1984/api/stream.mjpeg?src=camera1 ``` -**JPEG snapshots** +### jpeg + +Receiving a JPEG snapshot. ``` -http://192.168.1.123:1984/api/frame.jpeg?src=camera1 +curl http://192.168.1.123:1984/api/frame.jpeg?src=camera1 ``` - You can use `width`/`w` and/or `height`/`h` parameters. @@ -40,10 +50,14 @@ http://192.168.1.123:1984/api/frame.jpeg?src=camera1 - A cached snapshot will be used if its time is not older than the time specified in the `cache` parameter. - The `cache` parameter does not check the image dimensions from the cache and those specified in the query. -## Stream as ASCII to Terminal +### ascii + +Stream as ASCII to Terminal. This format is just for fun. You can boast to your friends that you can stream cameras even to the server console without a GUI. [![](https://img.youtube.com/vi/sHj_3h_sX7M/mqdefault.jpg)](https://www.youtube.com/watch?v=sHj_3h_sX7M) +> The demo video features a combination of several settings for this format with added audio. Of course, the format doesn't support audio out of the box. + **Tips** - this feature works only with MJPEG codec (use transcoding) @@ -78,3 +92,17 @@ streams: % curl "http://192.168.1.123:1984/api/stream.ascii?src=gamazda&back=8&text=%20%20" % curl "http://192.168.1.123:1984/api/stream.ascii?src=gamazda&text=helloworld" ``` + +### yuv4mpegpipe + +Raw [YUV](https://en.wikipedia.org/wiki/Y%E2%80%B2UV) frame stream with [YUV4MPEG](https://manned.org/yuv4mpeg) header. + +``` +ffplay http://192.168.1.123:1984/api/stream.y4m?src=camera1 +``` + +## Streaming ingest + +```shell +ffmpeg -re -i BigBuckBunny.mp4 -c mjpeg -f mpjpeg http://localhost:1984/api/stream.mjpeg?dst=camera1 +``` diff --git a/internal/mp4/README.md b/internal/mp4/README.md new file mode 100644 index 00000000..f2e32222 --- /dev/null +++ b/internal/mp4/README.md @@ -0,0 +1,66 @@ +# MP4 + +This module provides several features: + +1. MSE stream (fMP4 over WebSocket) +2. Camera snapshots in MP4 format (single frame), can be sent to [Telegram](#snapshot-to-telegram) +3. HTTP progressive streaming (MP4 file stream) - bad format for streaming because of high start delay. This format doesn't work in all Safari browsers, but go2rtc will automatically redirect it to HLS/fMP4 in this case. + +## API examples + +- MP4 snapshot: `http://192.168.1.123:1984/api/frame.mp4?src=camera1` (H264, H265) +- MP4 stream: `http://192.168.1.123:1984/api/stream.mp4?src=camera1` (H264, H265, AAC) +- MP4 file: `http://192.168.1.123:1984/api/stream.mp4?src=camera1` (H264, H265*, AAC, OPUS, MP3, PCMA, PCMU, PCM) + - You can use `mp4`, `mp4=flac` and `mp4=all` param for codec filters + - You can use `duration` param in seconds (ex. `duration=15`) + - You can use `filename` param (ex. `filename=record.mp4`) + - You can use `rotate` param with `90`, `180` or `270` values + - You can use `scale` param with positive integer values (ex. `scale=4:3`) + +Read more about [codecs filters](../../README.md#codecs-filters). + +**PS.** Rotate and scale params don't use transcoding and change video using metadata. + +## Snapshot to Telegram + +This examples for Home Assistant [Telegram Bot](https://www.home-assistant.io/integrations/telegram_bot/) integration. + +- change `url` to your go2rtc web API (`http://localhost:1984/` for most users) +- change `target` to your Telegram chat ID (support list) +- change `src=camera1` to your stream name from go2rtc config + +**Important.** Snapshot will be near instant for most cameras and many sources, except `ffmpeg` source. Because it takes a long time for ffmpeg to start streaming with video, even when you use `#video=copy`. Also the delay can be with cameras that do not start the stream with a keyframe. + +### Snapshot from H264 or H265 camera + +```yaml +service: telegram_bot.send_video +data: + url: http://localhost:1984/api/frame.mp4?src=camera1 + target: 123456789 +``` + +### Record from H264 or H265 camera + +Record from service call to the future. Doesn't support loopback. + +- `mp4=flac` - adds support PCM audio family +- `filename=record.mp4` - set name for downloaded file + +```yaml +service: telegram_bot.send_video +data: + url: http://localhost:1984/api/stream.mp4?src=camera1&mp4=flac&duration=5&filename=record.mp4 # duration in seconds + target: 123456789 +``` + +### Snapshot from JPEG or MJPEG camera + +This example works via the [mjpeg](../mjpeg/README.md) module. + +```yaml +service: telegram_bot.send_photo +data: + url: http://localhost:1984/api/frame.jpeg?src=camera1 + target: 123456789 +``` diff --git a/internal/mpegts/README.md b/internal/mpegts/README.md new file mode 100644 index 00000000..9ad83ac2 --- /dev/null +++ b/internal/mpegts/README.md @@ -0,0 +1,28 @@ +# MPEG-TS + +This module provides an [HTTP API](../api/README.md) for: + +- Streaming output in `mpegts` format. +- Streaming output in `adts` format. +- Streaming ingest in `mpegts` format. + +> [!NOTE] +> This module is probably better called mpeg. Because AAC is part of MPEG-2 and MPEG-4 and MPEG-TS is part of MPEG-2. + +## MPEG-TS Server + +```shell +ffplay http://localhost:1984/api/stream.ts?src=camera1 +``` + +## ADTS Server + +```shell +ffplay http://localhost:1984/api/stream.aac?src=camera1 +``` + +## Streaming ingest + +```shell +ffmpeg -re -i BigBuckBunny.mp4 -c copy -f mpegts http://localhost:1984/api/stream.ts?dst=camera1 +``` diff --git a/internal/multitrans/README.md b/internal/multitrans/README.md index 6201f8b6..ee483b8e 100644 --- a/internal/multitrans/README.md +++ b/internal/multitrans/README.md @@ -1,8 +1,8 @@ -# Multitrans +# TP-Link MULTITRANS -**added in v1.9.14** by [@forrestsocool](https://github.com/forrestsocool) +[`new in v1.9.14`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.14) by [@forrestsocool](https://github.com/forrestsocool) -Two-way audio support for Chinese version of [TP-Link cameras](https://www.tp-link.com.cn/list_2549.html). +Two-way audio support for Chinese version of [TP-Link](https://www.tp-link.com.cn/) cameras. ## Configuration @@ -14,3 +14,9 @@ streams: # two-way audio use MULTITRANS schema - multitrans://admin:admin@192.168.1.202:554 ``` + +## Useful links + +- https://www.tp-link.com.cn/list_2549.html +- https://github.com/AlexxIT/go2rtc/issues/1724 +- https://github.com/bingooo/hass-tplink-ipc/ diff --git a/internal/nest/README.md b/internal/nest/README.md new file mode 100644 index 00000000..d8e24d3d --- /dev/null +++ b/internal/nest/README.md @@ -0,0 +1,11 @@ +# Google Nest + +[`new in v1.6.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.6.0) + +For simplicity, it is recommended to connect the Nest/WebRTC camera to the [Home Assistant](../hass/README.md). +But if you can somehow get the below parameters, Nest/WebRTC source will work without Home Assistant. + +```yaml +streams: + nest-doorbell: nest:?client_id=***&client_secret=***&refresh_token=***&project_id=***&device_id=*** +``` diff --git a/internal/ngrok/README.md b/internal/ngrok/README.md index f0ba577e..bc5539e9 100644 --- a/internal/ngrok/README.md +++ b/internal/ngrok/README.md @@ -1,3 +1,5 @@ +# ngrok + With the ngrok integration, you can get external access to your streams when your Internet connection is behind a private IP address. - you may need external access for two different things: diff --git a/internal/onvif/README.md b/internal/onvif/README.md index ee922fbf..ec84a075 100644 --- a/internal/onvif/README.md +++ b/internal/onvif/README.md @@ -1,5 +1,22 @@ # ONVIF +## ONVIF Client + +[`new in v1.5.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.5.0) + +The source is not very useful if you already know RTSP and snapshot links for your camera. But it can be useful if you don't. + +**WebUI > Add** webpage support ONVIF autodiscovery. Your server must be on the same subnet as the camera. If you use Docker, you must use "network host". + +```yaml +streams: + dahua1: onvif://admin:password@192.168.1.123 + reolink1: onvif://admin:password@192.168.1.123:8000 + tapo1: onvif://admin:password@192.168.1.123:2020 +``` + +## ONVIF Server + A regular camera has a single video source (`GetVideoSources`) and two profiles (`GetProfiles`). Go2rtc has one video source and one profile per stream. diff --git a/internal/ring/README.md b/internal/ring/README.md new file mode 100644 index 00000000..a3464a79 --- /dev/null +++ b/internal/ring/README.md @@ -0,0 +1,17 @@ +# Ring + +[`new in v1.9.13`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.13) by [@seydx](https://github.com/seydx) + +This source type supports Ring cameras with [two-way audio](../../README.md#two-way-audio) support. + +## Configuration + +If you have a `refresh_token` and `device_id`, you can use them in the `go2rtc.yaml` config file. + +Otherwise, you can use the go2rtc web interface and add your Ring account (WebUI > Add > Ring). Once added, it will list all your Ring cameras. + +```yaml +streams: + ring: ring:?device_id=XXX&refresh_token=XXX + ring_snapshot: ring:?device_id=XXX&refresh_token=XXX&snapshot +``` diff --git a/internal/roborock/README.md b/internal/roborock/README.md new file mode 100644 index 00000000..33612006 --- /dev/null +++ b/internal/roborock/README.md @@ -0,0 +1,15 @@ +# Roborock + +[`new in v1.3.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0) + +This source type supports Roborock vacuums with cameras. Known working models: + +- **Roborock S6 MaxV** - only video (the vacuum has no microphone) +- **Roborock S7 MaxV** - video and two-way audio +- **Roborock Qrevo MaxV** - video and two-way audio + +## Configuration + +This source supports loading Roborock credentials from the Home Assistant [custom integration](https://github.com/humbertogontijo/homeassistant-roborock) or the [core integration](https://www.home-assistant.io/integrations/roborock). Otherwise, you need to log in to your Roborock account (MiHome account is not supported). Go to go2rtc WebUI > Add webpage. Copy the `roborock://...` source for your vacuum and paste it into your `go2rtc.yaml` config. + +If you have a pattern PIN for your vacuum, add it as a numeric PIN (lines: 123, 456, 789) to the end of the `roborock` link. diff --git a/internal/rtmp/README.md b/internal/rtmp/README.md index ce340e63..c677916d 100644 --- a/internal/rtmp/README.md +++ b/internal/rtmp/README.md @@ -1,3 +1,61 @@ +# Real-Time Messaging Protocol + +This module provides the following features for the RTMP protocol: + +- Streaming input - [RTMP client](#rtmp-client) +- Streaming output and ingest in `rtmp` format - [RTMP server](#rtmp-server) +- Streaming output and ingest in `flv` format - [FLV server](#flv-server) + +## RTMP Client + +You can get a stream from an RTMP server, for example [Nginx with nginx-rtmp-module](https://github.com/arut/nginx-rtmp-module). + +### Client Configuration + +```yaml +streams: + rtmp_stream: rtmp://192.168.1.123/live/camera1 +``` + +## RTMP Server + +[`new in v1.8.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.8.0) + +Streaming output stream in `rtmp` format: + +```shell +ffplay rtmp://localhost:1935/camera1 +``` + +Streaming ingest stream in `rtmp` format: + +```shell +ffmpeg -re -i BigBuckBunny.mp4 -c copy -f flv rtmp://localhost:1935/camera1 +``` + +### Server Configuration + +By default, the RTMP server is disabled. + +```yaml +rtmp: + listen: ":1935" # by default - disabled! +``` + +## FLV Server + +Streaming output in `flv` format. + +```shell +ffplay http://localhost:1984/stream.flv?src=camera1 +``` + +Streaming ingest in `flv` format. + +```shell +ffmpeg -re -i BigBuckBunny.mp4 -c copy -f flv http://localhost:1984/api/stream.flv?dst=camera1 +``` + ## Tested client | From | To | Comment | diff --git a/internal/rtsp/README.md b/internal/rtsp/README.md new file mode 100644 index 00000000..cd7c84af --- /dev/null +++ b/internal/rtsp/README.md @@ -0,0 +1,93 @@ +# Real Time Streaming Protocol + +This module provides the following features for the RTSP protocol: + + - Streaming input - [RTSP client](#rtsp-client) + - Streaming output - [RTSP server](#rtsp-server) + - [Streaming ingest](#streaming-ingest) + - [Two-way audio](#two-way-audio) + +## RTSP Client + +### Configuration + +```yaml +streams: + sonoff_camera: rtsp://rtsp:12345678@192.168.1.123/av_stream/ch0 + dahua_camera: + - rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0&unicast=true&proto=Onvif + - rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=1#backchannel=0 + amcrest_doorbell: + - rtsp://username:password@192.168.1.123:554/cam/realmonitor?channel=1&subtype=0#backchannel=0 + unifi_camera: rtspx://192.168.1.123:7441/fD6ouM72bWoFijxK + glichy_camera: ffmpeg:rtsp://username:password@192.168.1.123/live/ch00_1 +``` + +### Recommendations + +- **Amcrest Doorbell** users may want to disable two-way audio, because with an active stream, you won't have a working call button. You need to add `#backchannel=0` to the end of your RTSP link in YAML config file +- **Dahua Doorbell** users may want to change [audio codec](https://github.com/AlexxIT/go2rtc/issues/49#issuecomment-2127107379) for proper two-way audio. Make sure not to request backchannel multiple times by adding `#backchannel=0` to other stream sources of the same doorbell. The `unicast=true&proto=Onvif` is preferred for two-way audio as this makes the doorbell accept multiple codecs for the incoming audio +- **Reolink** users may want NOT to use RTSP protocol at all, some camera models have a very awful, unusable stream implementation +- **Ubiquiti UniFi** users may want to disable HTTPS verification. Use `rtspx://` prefix instead of `rtsps://`. And don't use `?enableSrtp` [suffix](https://github.com/AlexxIT/go2rtc/issues/81) +- **TP-Link Tapo** users may skip login and password, because go2rtc supports login [without them](https://drmnsamoliu.github.io/video.html) +- If your camera has two RTSP links, you can add both as sources. This is useful when streams have different codecs, for example AAC audio with main stream and PCMU/PCMA audio with second stream +- If the stream from your camera is glitchy, try using [ffmpeg source](../ffmpeg/README.md). It will not add CPU load if you don't use transcoding +- If the stream from your camera is very glitchy, try to use transcoding with [ffmpeg source](../ffmpeg/README.md) + +### Other options + +Format: `rtsp...#{param1}#{param2}#{param3}` + +- Add custom timeout `#timeout=30` (in seconds) +- Ignore audio - `#media=video` or ignore video - `#media=audio` +- Ignore two-way audio API `#backchannel=0` - important for some glitchy cameras +- Use WebSocket transport `#transport=ws...` + +### RTSP over WebSocket + +```yaml +streams: + # WebSocket with authorization, RTSP - without + axis-rtsp-ws: rtsp://192.168.1.123:4567/axis-media/media.amp?overview=0&camera=1&resolution=1280x720&videoframeskipmode=empty&Axis-Orig-Sw=true#transport=ws://user:pass@192.168.1.123:4567/rtsp-over-websocket + # WebSocket without authorization, RTSP - with + dahua-rtsp-ws: rtsp://user:pass@192.168.1.123/cam/realmonitor?channel=1&subtype=1&proto=Private3#transport=ws://192.168.1.123/rtspoverwebsocket +``` + +## RTSP Server + +You can get any stream as RTSP-stream: `rtsp://192.168.1.123:8554/{stream_name}` + +You can enable external password protection for your RTSP streams. Password protection is always disabled for localhost calls (ex. FFmpeg or Home Assistant on the same server). + +### Configuration + +```yaml +rtsp: + listen: ":8554" # RTSP Server TCP port, default - 8554 + username: "admin" # optional, default - disabled + password: "pass" # optional, default - disabled + default_query: "video&audio" # optional, default codecs filters +``` + +By default go2rtc provide RTSP-stream with only one first video and only one first audio. You can change it with the `default_query` setting: + +- `default_query: "mp4"` - MP4 compatible codecs (H264, H265, AAC) +- `default_query: "video=all&audio=all"` - all tracks from all source (not all players can handle this) +- `default_query: "video=h264,h265"` - only one video track (H264 or H265) +- `default_query: "video&audio=all"` - only one first any video and all audio as separate tracks + +Read more about [codecs filters](../../README.md#codecs-filters). + +## Streaming ingest + +```shell +ffmpeg -re -i BigBuckBunny.mp4 -c copy -rtsp_transport tcp -f rtsp rtsp://localhost:8554/camera1 +``` + +## Two-way audio + +Before purchasing, it is difficult to understand whether the camera supports two-way audio via the RTSP protocol or not. This isn't usually mentioned in a camera's description. You can only find out by reading reviews from real buyers. + +A camera is considered to support two-way audio if it supports the ONVIF Profile T protocol. But in reality, this isn't always the case. And the ONVIF protocol has no connection with the camera's RTSP implementation. + +In go2rtc you can find out if the camera supports two-way audio via WebUI > stream probe. diff --git a/internal/srtp/README.md b/internal/srtp/README.md new file mode 100644 index 00000000..9bc36d0d --- /dev/null +++ b/internal/srtp/README.md @@ -0,0 +1,13 @@ +# SRTP + +This is a support module for the [HomeKit](../homekit/README.md) module. + +> [!NOTE] +> This module can be removed and its functionality transferred to the homekit module. + +## Configuration + +```yaml +srtp: + listen: :8443 # enabled by default +``` diff --git a/internal/streams/README.md b/internal/streams/README.md index 6f0c9772..2f3eb392 100644 --- a/internal/streams/README.md +++ b/internal/streams/README.md @@ -1,3 +1,89 @@ +# Streams + +This core module is responsible for managing the stream list. + +## Stream to camera + +[`new in v1.3.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0) + +go2rtc supports playing audio files (ex. music or [TTS](https://www.home-assistant.io/integrations/#text-to-speech)) and live streams (ex. radio) on cameras with [two-way audio](../../README.md#two-way-audio) support. + +API example: + +```text +POST http://localhost:1984/api/streams?dst=camera1&src=ffmpeg:http://example.com/song.mp3#audio=pcma#input=file +``` + +- you can stream: local files, web files, live streams or any format, supported by FFmpeg +- you should use [ffmpeg source](../ffmpeg/README.md) for transcoding audio to codec, that your camera supports +- you can check camera codecs on the go2rtc WebUI info page when the stream is active +- some cameras support only low quality `PCMA/8000` codec (ex. [Tapo](../tapo/README.md)) +- it is recommended to choose higher quality formats if your camera supports them (ex. `PCMA/48000` for some Dahua cameras) +- if you play files over `http` link, you need to add `#input=file` params for transcoding, so the file will be transcoded and played in real time +- if you play live streams, you should skip `#input` param, because it is already in real time +- you can stop active playback by calling the API with the empty `src` parameter +- you will see one active producer and one active consumer in go2rtc WebUI info page during streaming + +## Publish stream + +[`new in v1.8.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.8.0) + +You can publish any stream to streaming services (YouTube, Telegram, etc.) via RTMP/RTMPS. Important: + +- Supported codecs: H264 for video and AAC for audio +- AAC audio is required for YouTube; videos without audio will not work +- You don't need to enable [RTMP module](../rtmp/README.md) listening for this task + +You can use the API: + +```text +POST http://localhost:1984/api/streams?src=camera1&dst=rtmps://... +``` + +Or config file: + +```yaml +publish: + # publish stream "video_audio_transcode" to Telegram + video_audio_transcode: + - rtmps://xxx-x.rtmp.t.me/s/xxxxxxxxxx:xxxxxxxxxxxxxxxxxxxxxx + # publish stream "audio_transcode" to Telegram and YouTube + audio_transcode: + - rtmps://xxx-x.rtmp.t.me/s/xxxxxxxxxx:xxxxxxxxxxxxxxxxxxxxxx + - rtmp://xxx.rtmp.youtube.com/live2/xxxx-xxxx-xxxx-xxxx-xxxx + +streams: + video_audio_transcode: + - ffmpeg:rtsp://user:pass@192.168.1.123/stream1#video=h264#hardware#audio=aac + audio_transcode: + - ffmpeg:rtsp://user:pass@192.168.1.123/stream1#video=copy#audio=aac +``` + +- **Telegram Desktop App** > Any public or private channel or group (where you admin) > Live stream > Start with... > Start streaming. +- **YouTube** > Create > Go live > Stream latency: Ultra low-latency > Copy: Stream URL + Stream key. + +## Preload stream + +[`new in v1.9.11`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.11) + +You can preload any stream on go2rtc start. This is useful for cameras that take a long time to start up. + +```yaml +preload: + camera1: # default: video&audio = ANY + camera2: "video" # preload only video track + camera3: "video=h264&audio=opus" # preload H264 video and OPUS audio + +streams: + camera1: + - rtsp://192.168.1.100/stream + camera2: + - rtsp://192.168.1.101/stream + camera3: + - rtsp://192.168.1.102/h265stream + - ffmpeg:camera3#video=h264#audio=opus#hardware +``` + ## Examples ```yaml diff --git a/internal/tapo/README.md b/internal/tapo/README.md new file mode 100644 index 00000000..e8723d25 --- /dev/null +++ b/internal/tapo/README.md @@ -0,0 +1,61 @@ +# TP-Link Tapo + +[`new in v1.2.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.2.0) + +[TP-Link Tapo](https://www.tapo.com/) proprietary camera protocol with **two-way audio** support. + +- stream quality is the same as [RTSP protocol](https://www.tapo.com/en/faq/34/) +- use the **cloud password**, this is not the RTSP password! you do not need to add a login! +- you can also use **UPPERCASE** MD5 hash from your cloud password with `admin` username +- some new camera firmwares require SHA256 instead of MD5 + +## Configuration + +```yaml +streams: + # cloud password without username + camera1: tapo://cloud-password@192.168.1.123 + # admin username and UPPERCASE MD5 cloud-password hash + camera2: tapo://admin:UPPERCASE-MD5@192.168.1.123 + # admin username and UPPERCASE SHA256 cloud-password hash + camera3: tapo://admin:UPPERCASE-SHA256@192.168.1.123 + # VGA stream (the so called substream, the lower resolution one) + camera4: tapo://cloud-password@192.168.1.123?subtype=1 + # HD stream (default) + camera5: tapo://cloud-password@192.168.1.123?subtype=0 +``` + +```bash +echo -n "cloud password" | md5 | awk '{print toupper($0)}' +echo -n "cloud password" | shasum -a 256 | awk '{print toupper($0)}' +``` + +## TP-Link Kasa + +[`new in v1.7.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.7.0) + +> [!NOTE] +> This source should be moved to separate module. Because it's source code not related to Tapo. + +[TP-Link Kasa](https://www.kasasmart.com/) non-standard protocol [more info](https://medium.com/@hu3vjeen/reverse-engineering-tp-link-kc100-bac4641bf1cd). + +- `username` - urlsafe email, `alex@gmail.com` -> `alex%40gmail.com` +- `password` - base64password, `secret1` -> `c2VjcmV0MQ==` + +```yaml +streams: + kc401: kasa://username:password@192.168.1.123:19443/https/stream/mixed +``` + +Tested: KD110, KC200, KC401, KC420WS, EC71. + +## TP-Link Vigi + +[`new in v1.9.8`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.8) + +[TP-Link VIGI](https://www.vigi.com/) cameras. These are cameras from a different sub-brand, but the format is very similar to Tapo. Only the authorization is different. Read more [here](https://github.com/AlexxIT/go2rtc/issues/1470). + +```yaml +streams: + camera1: vigi://admin:{password}@192.168.1.123 +``` diff --git a/internal/tuya/README.md b/internal/tuya/README.md index 34502748..e9295ee7 100644 --- a/internal/tuya/README.md +++ b/internal/tuya/README.md @@ -1,12 +1,12 @@ # Tuya -*[New in v1.9.13](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.13)* +[`new in v1.9.13`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.13) by [@seydx](https://github.com/seydx) [Tuya](https://www.tuya.com/) is a proprietary camera protocol with **two-way audio** support. go2rtc supports `Tuya Smart API` and `Tuya Cloud API`. **Tuya Smart API (recommended)**: +- **Smart Life accounts are NOT supported**, you need to create a Tuya Smart account. If the cameras are already added to the Smart Life app, you need to remove them and add them again to the [Tuya Smart](https://play.google.com/store/apps/details?id=com.tuya.smart) app. - Cameras can be discovered through the go2rtc web interface via Tuya Smart account (Add > Tuya > Select region and fill in email and password > Login). -- **Smart Life accounts are not supported**, you need to create a Tuya Smart account. If the cameras are already added to the Smart Life app, you need to remove them and add them again to the Tuya Smart app. **Tuya Cloud API**: - Requires setting up a cloud project in the Tuya Developer Platform. diff --git a/internal/v4l2/README.md b/internal/v4l2/README.md index 1c5dd390..8731cf4c 100644 --- a/internal/v4l2/README.md +++ b/internal/v4l2/README.md @@ -1,4 +1,6 @@ -# V4L2 +# Video4Linux + +[`new in v1.9.9`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.9) What you should to know about [V4L2](https://en.wikipedia.org/wiki/Video4Linux): diff --git a/internal/webrtc/README.md b/internal/webrtc/README.md index eb553ba4..baabe57b 100644 --- a/internal/webrtc/README.md +++ b/internal/webrtc/README.md @@ -1,3 +1,86 @@ +# WebRTC + +## WebRTC Client + +[`new in v1.3.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0) + +This source type supports four connection formats. + +### Creality + +[`new in v1.9.10`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.10) + +[Creality](https://www.creality.com/) 3D printer camera. Read more [here](https://github.com/AlexxIT/go2rtc/issues/1600). + +```yaml +streams: + creality_k2p: webrtc:http://192.168.1.123:8000/call/webrtc_local#format=creality +``` + +### go2rtc + +This format is only supported in go2rtc. Unlike WHEP, it supports asynchronous WebRTC connections and two-way audio. + +```yaml +streams: + webrtc-go2rtc: webrtc:ws://192.168.1.123:1984/api/ws?src=camera1 +``` + +### Kinesis + +[`new in v1.6.1`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.6.1) + +Supports [Amazon Kinesis Video Streams](https://aws.amazon.com/kinesis/video-streams/), using WebRTC protocol. You need to specify the signaling WebSocket URL with all credentials in query params, `client_id` and `ice_servers` list in [JSON format](https://developer.mozilla.org/en-US/docs/Web/API/RTCIceServer). + +```yaml +streams: + webrtc-kinesis: webrtc:wss://...amazonaws.com/?...#format=kinesis#client_id=...#ice_servers=[{...},{...}] +``` + +**PS.** For `kinesis` sources, you can use [echo](../echo/README.md) to get connection params using `bash`, `python` or any other script language. + +### OpenIPC + +[`new in v1.7.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.7.0) + +Cameras on open-source [OpenIPC](https://openipc.org/) firmware. + +```yaml +streams: + webrtc-openipc: webrtc:ws://192.168.1.123/webrtc_ws#format=openipc#ice_servers=[{"urls":"stun:stun.kinesisvideo.eu-north-1.amazonaws.com:443"}] +``` + +### SwitchBot + +Support connection to [SwitchBot](https://us.switch-bot.com/) cameras that are based on Kinesis Video Streams. Specifically, this includes [Pan/Tilt Cam Plus 2K](https://us.switch-bot.com/pages/switchbot-pan-tilt-cam-plus-2k) and [Pan/Tilt Cam Plus 3K](https://us.switch-bot.com/pages/switchbot-pan-tilt-cam-plus-3k) and [Smart Video Doorbell](https://www.switchbot.jp/products/switchbot-smart-video-doorbell). `Outdoor Spotlight Cam 1080P`, `Outdoor Spotlight Cam 2K`, `Pan/Tilt Cam`, `Pan/Tilt Cam 2K`, `Indoor Cam` are based on Tuya, so this feature is not available. + +```yaml +streams: + webrtc-switchbot: webrtc:wss://...amazonaws.com/?...#format=switchbot#resolution=hd#play_type=0#client_id=...#ice_servers=[{...},{...}] +``` + +### WHEP + +[WebRTC/WHEP](https://datatracker.ietf.org/doc/draft-murillo-whep/) is replaced by [WebRTC/WISH](https://datatracker.ietf.org/doc/charter-ietf-wish/02/) standard for WebRTC video/audio viewers. But it may already be supported in some third-party software. It is supported in go2rtc. + +```yaml +streams: + webrtc-whep: webrtc:http://192.168.1.123:1984/api/webrtc?src=camera1 +``` + +### Wyze + +[`new in v1.6.1`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.6.1) + +Legacy method to connect to [Wyze](https://www.wyze.com/) cameras using WebRTC protocol via [docker-wyze-bridge](https://github.com/mrlt8/docker-wyze-bridge). For native P2P support without docker-wyze-bridge, see [Source: Wyze](../wyze/README.md). + +```yaml +streams: + webrtc-wyze: webrtc:http://192.168.1.123:5000/signaling/camera1?kvs#format=wyze +``` + +## WebRTC Server + What you should know about WebRTC: - It's almost always a **direct [peer-to-peer](https://en.wikipedia.org/wiki/Peer-to-peer) connection** from your browser to the go2rtc app @@ -15,16 +98,58 @@ If an external connection via STUN is used: - https://habr.com/ru/companies/flashphoner/articles/480006/ - https://www.youtube.com/watch?v=FXVg2ckuKfs -## Default config +### Confiration suggestions + +- by default, WebRTC uses both TCP and UDP on port 8555 for connections +- you can use this port for external access +- you can change the port in YAML config: ```yaml webrtc: - listen: ":8555" - ice_servers: - - urls: [ "stun:stun.l.google.com:19302" ] + listen: ":8555" # address of your local server and port (TCP/UDP) ``` -## Config +#### Static public IP + +- forward the port 8555 on your router (you can use the same 8555 port or any other as external port) +- add your external IP address and external port to the YAML config + +```yaml +webrtc: + candidates: + - 216.58.210.174:8555 # if you have a static public IP address +``` + +#### Dynamic public IP + +- forward the port 8555 on your router (you can use the same 8555 port or any other as the external port) +- add `stun` word and external port to YAML config + - go2rtc automatically detects your external address with STUN server + +```yaml +webrtc: + candidates: + - stun:8555 # if you have a dynamic public IP address +``` + +#### Hard tech way 1. Own TCP-tunnel + +If you have a personal [VPS](https://en.wikipedia.org/wiki/Virtual_private_server), you can create a TCP tunnel and setup in the same way as "Static public IP". But use your VPS IP address in the YAML config. + +#### Hard tech way 2. Using TURN-server + +If you have personal [VPS](https://en.wikipedia.org/wiki/Virtual_private_server), you can install TURN server (e.g. [coturn](https://github.com/coturn/coturn), config [example](https://github.com/AlexxIT/WebRTC/wiki/Coturn-Example)). + +```yaml +webrtc: + ice_servers: + - urls: [stun:stun.l.google.com:19302] + - urls: [turn:123.123.123.123:3478] + username: your_user + credential: your_pass +``` + +### Full configuration **Important!** This example is not for copy/pasting! @@ -82,7 +207,7 @@ You can set a **fixed TCP** port and a **random UDP** port for all connections: You can also disable the TCP port and leave only random UDP ports: `listen: ""`. -## Config filters +### Configuration filters **Important!** By default, go2rtc excludes all Docker-like candidates (`172.16.0.0/12`). This cannot be disabled. @@ -106,6 +231,28 @@ webrtc: candidates: [ 192.168.1.2:8555 ] # add manual host candidate (use docker port forwarding) ``` +## Streaming ingest + +### Ingest: Browser + +[`new in v1.3.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0) + +You can turn the browser of any PC or mobile into an IP camera with support for video and two-way audio. Or even broadcast your PC screen: + +1. Create empty stream in the `go2rtc.yaml` +2. Go to go2rtc WebUI +3. Open `links` page for your stream +4. Select `camera+microphone` or `display+speaker` option +5. Open `webrtc` local page (your go2rtc **should work over HTTPS!**) or `share link` via [WebTorrent](../webtorrent/README.md) technology (work over HTTPS by default) + +### Ingest: WHIP + +[`new in v1.3.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0) + +You can use **OBS Studio** or any other broadcast software with [WHIP](https://www.ietf.org/archive/id/draft-ietf-wish-whip-01.html) protocol support. This standard has not yet been approved. But you can download OBS Studio [dev version](https://github.com/obsproject/obs-studio/actions/runs/3969201209): + +- Settings > Stream > Service: WHIP > `http://192.168.1.123:1984/api/webrtc?dst=camera1` + ## Useful links - https://www.ietf.org/archive/id/draft-ietf-wish-whip-01.html diff --git a/internal/webtorrent/README.md b/internal/webtorrent/README.md new file mode 100644 index 00000000..1c9811ad --- /dev/null +++ b/internal/webtorrent/README.md @@ -0,0 +1,45 @@ +# WebTorrent + +> [!NOTE] +> This section needs some improvement. + +## WebTorrent Client + +[`new in v1.3.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0) + +This source can get a stream from another go2rtc via [WebTorrent](https://en.wikipedia.org/wiki/WebTorrent) protocol. + +### Client Configuration + +```yaml +streams: + webtorrent1: webtorrent:?share=huofssuxaty00izc&pwd=k3l2j9djeg8v8r7e +``` + +## WebTorrent Server + +[`new in v1.3.0`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.3.0) + +This module supports: + +- Share any local stream via [WebTorrent](https://webtorrent.io/) technology +- Get any [incoming stream](../webrtc/README.md#ingest-browser) from PC or mobile via [WebTorrent](https://webtorrent.io/) technology +- Get any remote go2rtc source via [WebTorrent](https://webtorrent.io/) technology + +Securely and freely. You do not need to open a public access to the go2rtc server. But in some cases (Symmetric NAT), you may need to set up external access to [WebRTC module](../webrtc/README.md). + +To generate a sharing link or incoming link, go to the go2rtc WebUI (stream links page). This link is **temporary** and will stop working after go2rtc is restarted! + +### Server Configuration + +You can create permanent external links in the go2rtc config: + +```yaml +webtorrent: + shares: + super-secret-share: # share name, should be unique among all go2rtc users! + pwd: super-secret-password + src: rtsp-dahua1 # stream name from streams section +``` + +Link example: `https://go2rtc.org/webtorrent/#share=02SNtgjKXY&pwd=wznEQqznxW&media=video+audio` diff --git a/internal/wyoming/README.md b/internal/wyoming/README.md index f98acb05..f3c00191 100644 --- a/internal/wyoming/README.md +++ b/internal/wyoming/README.md @@ -1,5 +1,8 @@ # Wyoming +> [!NOTE] +> The format is under development and does not yet work stably. + This module provide [Wyoming Protocol](https://www.home-assistant.io/integrations/wyoming/) support to create local voice assistants using [Home Assistant](https://www.home-assistant.io/). - go2rtc can act as [Wyoming Satellite](https://github.com/rhasspy/wyoming-satellite) diff --git a/internal/wyze/README.md b/internal/wyze/README.md index ca7cf6c4..22b3d355 100644 --- a/internal/wyze/README.md +++ b/internal/wyze/README.md @@ -1,5 +1,7 @@ # Wyze +[`new in v1.9.14`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.14) by [@seydx](https://github.com/seydx) + This source allows you to stream from [Wyze](https://wyze.com/) cameras using native P2P protocol without the Wyze app or SDK. **Important:** @@ -44,14 +46,14 @@ The stream URL is automatically generated when you add cameras via the WebUI: wyze://[IP]?uid=[P2P_ID]&enr=[ENR]&mac=[MAC]&model=[MODEL]&subtype=[hd|sd]&dtls=true ``` -| Parameter | Description | -|-----------|-------------| -| `IP` | Camera's local IP address | -| `uid` | P2P identifier (20 chars) | -| `enr` | Encryption key for DTLS | -| `mac` | Device MAC address | -| `model` | Camera model (e.g., HL_CAM4) | -| `dtls` | Enable DTLS encryption (default: true) | +| Parameter | Description | +|-----------|-------------------------------------------------| +| `IP` | Camera's local IP address | +| `uid` | P2P identifier (20 chars) | +| `enr` | Encryption key for DTLS | +| `mac` | Device MAC address | +| `model` | Camera model (e.g., HL_CAM4) | +| `dtls` | Enable DTLS encryption (default: true) | | `subtype` | Camera resolution: `hd` or `sd` (default: `hd`) | ## Configuration @@ -72,35 +74,35 @@ Two-way audio (intercom) is supported automatically. When a consumer sends audio ## Camera Compatibility -| Name | Model | Firmware | Protocol | Encryption | Codecs | -|------|-------|----------|----------|------------|--------| -| Wyze Cam v4 | HL_CAM4 | 4.52.9.4188 | TUTK | TransCode | h264, aac | -| | | 4.52.9.5332 | TUTK | HMAC-SHA1 | h264, aac | -| Wyze Cam v3 Pro | | | TUTK | | | -| Wyze Cam v3 | WYZE_CAKP2JFUS | 4.36.14.3497 | TUTK | TransCode | h264, pcm | -| Wyze Cam v2 | WYZEC1-JZ | 4.9.9.3006 | TUTK | TransCode | h264, pcmu | -| Wyze Cam v1 | | | TUTK | | | -| Wyze Cam Pan v4 | | | Gwell* | | | -| Wyze Cam Pan v3 | | | TUTK | | | -| Wyze Cam Pan v2 | | | TUTK | | | -| Wyze Cam Pan v1 | | | TUTK | | | -| Wyze Cam OG | | | Gwell* | | | -| Wyze Cam OG Telephoto | | | Gwell* | | | -| Wyze Cam OG (2025) | | | Gwell* | | | -| Wyze Cam Outdoor v2 | | | TUTK | | | -| Wyze Cam Outdoor v1 | | | TUTK | | | -| Wyze Cam Floodlight Pro | | | ? | | | -| Wyze Cam Floodlight v2 | | | TUTK | | | -| Wyze Cam Floodlight | | | TUTK | | | -| Wyze Video Doorbell v2 | HL_DB2 | 4.51.3.4992 | TUTK | TransCode | h264, pcm | -| Wyze Video Doorbell v1 | | | TUTK | | | -| Wyze Video Doorbell Pro | | | ? | | | -| Wyze Battery Video Doorbell | | | ? | | | -| Wyze Duo Cam Doorbell | | | ? | | | -| Wyze Battery Cam Pro | | | ? | | | -| Wyze Solar Cam Pan | | | ? | | | -| Wyze Duo Cam Pan | | | ? | | | -| Wyze Window Cam | | | ? | | | -| Wyze Bulb Cam | | | ? | | | +| Name | Model | Firmware | Protocol | Encryption | Codecs | +|-----------------------------|----------------|--------------|----------|------------|------------| +| Wyze Cam v4 | HL_CAM4 | 4.52.9.4188 | TUTK | TransCode | h264, aac | +| | | 4.52.9.5332 | TUTK | HMAC-SHA1 | h264, aac | +| Wyze Cam v3 Pro | | | TUTK | | | +| Wyze Cam v3 | WYZE_CAKP2JFUS | 4.36.14.3497 | TUTK | TransCode | h264, pcm | +| Wyze Cam v2 | WYZEC1-JZ | 4.9.9.3006 | TUTK | TransCode | h264, pcmu | +| Wyze Cam v1 | | | TUTK | | | +| Wyze Cam Pan v4 | | | Gwell* | | | +| Wyze Cam Pan v3 | | | TUTK | | | +| Wyze Cam Pan v2 | | | TUTK | | | +| Wyze Cam Pan v1 | | | TUTK | | | +| Wyze Cam OG | | | Gwell* | | | +| Wyze Cam OG Telephoto | | | Gwell* | | | +| Wyze Cam OG (2025) | | | Gwell* | | | +| Wyze Cam Outdoor v2 | | | TUTK | | | +| Wyze Cam Outdoor v1 | | | TUTK | | | +| Wyze Cam Floodlight Pro | | | ? | | | +| Wyze Cam Floodlight v2 | | | TUTK | | | +| Wyze Cam Floodlight | | | TUTK | | | +| Wyze Video Doorbell v2 | HL_DB2 | 4.51.3.4992 | TUTK | TransCode | h264, pcm | +| Wyze Video Doorbell v1 | | | TUTK | | | +| Wyze Video Doorbell Pro | | | ? | | | +| Wyze Battery Video Doorbell | | | ? | | | +| Wyze Duo Cam Doorbell | | | ? | | | +| Wyze Battery Cam Pro | | | ? | | | +| Wyze Solar Cam Pan | | | ? | | | +| Wyze Duo Cam Pan | | | ? | | | +| Wyze Window Cam | | | ? | | | +| Wyze Bulb Cam | | | ? | | | _* Gwell based protocols are not yet supported._ diff --git a/internal/xiaomi/README.md b/internal/xiaomi/README.md index c0cabcd3..330183e8 100644 --- a/internal/xiaomi/README.md +++ b/internal/xiaomi/README.md @@ -1,6 +1,6 @@ -# Xiaomi +# Xiaomi Mi Home -**Added in v1.9.13. Improved in v1.9.14.** +[`new in v1.9.13`](https://github.com/AlexxIT/go2rtc/releases/tag/v1.9.13) This source allows you to view cameras from the [Xiaomi Mi Home](https://home.mi.com/) ecosystem. diff --git a/internal/yandex/README.md b/internal/yandex/README.md index 951e1e99..69d47398 100644 --- a/internal/yandex/README.md +++ b/internal/yandex/README.md @@ -12,7 +12,7 @@ Source for receiving stream from new [Yandex IP camera](https://alice.yandex.ru/ 1. Open this link in any browser: https://iot.quasar.yandex.ru/m/v3/user/devices 2. Copy ID of your camera, key: `"id"`. -## Config examples +## Configuration ```yaml streams: diff --git a/package.json b/package.json index af5c7a70..03377f46 100644 --- a/package.json +++ b/package.json @@ -1,13 +1,14 @@ { "devDependencies": { - "eslint": "^8.44.0", - "eslint-plugin-html": "^7.1.0", - "vitepress": "^2.0.0-alpha.15" + "@types/node": "^25.2.0", + "eslint": "^9.39.2", + "eslint-plugin-html": "^8.1.4", + "vitepress": "^2.0.0-alpha.16" }, "scripts": { - "docs:dev": "vitepress dev .", - "docs:build": "vitepress build .", - "docs:preview": "vitepress preview ." + "docs:dev": "vitepress dev website --host", + "docs:build": "vitepress build website", + "docs:preview": "vitepress preview website" }, "eslintConfig": { "env": { @@ -42,8 +43,5 @@ } } ] - }, - "dependencies": { - "@catppuccin/vitepress": "^0.1.2" } -} \ No newline at end of file +} diff --git a/pkg/ffmpeg/README.md b/pkg/ffmpeg/README.md new file mode 100644 index 00000000..157cfdfe --- /dev/null +++ b/pkg/ffmpeg/README.md @@ -0,0 +1,68 @@ +## FFplay output + +[FFplay](https://stackoverflow.com/questions/27778678/what-are-mv-fd-aq-vq-sq-and-f-in-a-video-stream) `7.11 A-V: 0.003 fd= 1 aq= 21KB vq= 321KB sq= 0B f=0/0`: + +- `7.11` - master clock, is the time from start of the stream/video +- `A-V` - av_diff, difference between audio and video timestamps +- `fd` - frames dropped +- `aq` - audio queue (0 - no delay) +- `vq` - video queue (0 - no delay) +- `sq` - subtitle queue +- `f` - timestamp error correction rate (Not 100% sure) + +`M-V`, `M-A` means video stream only, audio stream only respectively. + +## Devices Windows + +``` +>ffmpeg -hide_banner -f dshow -list_options true -i video="VMware Virtual USB Video Device" +[dshow @ 0000025695e52900] DirectShow video device options (from video devices) +[dshow @ 0000025695e52900] Pin "Record" (alternative pin name "0") +[dshow @ 0000025695e52900] pixel_format=yuyv422 min s=1280x720 fps=1 max s=1280x720 fps=10 +[dshow @ 0000025695e52900] pixel_format=yuyv422 min s=1280x720 fps=1 max s=1280x720 fps=10 (tv, bt470bg/bt709/unknown, topleft) +[dshow @ 0000025695e52900] pixel_format=nv12 min s=1280x720 fps=1 max s=1280x720 fps=23 +[dshow @ 0000025695e52900] pixel_format=nv12 min s=1280x720 fps=1 max s=1280x720 fps=23 (tv, bt470bg/bt709/unknown, topleft) +``` + +## Devices Mac + +``` +% ./ffmpeg -hide_banner -f avfoundation -list_devices true -i "" +[AVFoundation indev @ 0x7f8b1f504d80] AVFoundation video devices: +[AVFoundation indev @ 0x7f8b1f504d80] [0] FaceTime HD Camera +[AVFoundation indev @ 0x7f8b1f504d80] [1] Capture screen 0 +[AVFoundation indev @ 0x7f8b1f504d80] AVFoundation audio devices: +[AVFoundation indev @ 0x7f8b1f504d80] [0] Soundflower (2ch) +[AVFoundation indev @ 0x7f8b1f504d80] [1] Built-in Microphone +[AVFoundation indev @ 0x7f8b1f504d80] [2] Soundflower (64ch) +``` + +## Devices Linux + +``` +# ffmpeg -hide_banner -f v4l2 -list_formats all -i /dev/video0 +[video4linux2,v4l2 @ 0x7f7de7c58bc0] Raw : yuyv422 : YUYV 4:2:2 : 640x480 160x120 176x144 320x176 320x240 352x288 432x240 544x288 640x360 752x416 800x448 800x600 864x480 960x544 960x720 1024x576 1184x656 1280x720 1280x960 +[video4linux2,v4l2 @ 0x7f7de7c58bc0] Compressed: mjpeg : Motion-JPEG : 640x480 160x120 176x144 320x176 320x240 352x288 432x240 544x288 640x360 752x416 800x448 800x600 864x480 960x544 960x720 1024x576 1184x656 1280x720 1280x960 +``` + +## TTS + +```yaml +streams: + tts: ffmpeg:#input=-readrate 1 -readrate_initial_burst 0.001 -f lavfi -i "flite=text='1 2 3 4 5 6 7 8 9 0'"#audio=pcma +``` + +## Useful links + +- https://superuser.com/questions/564402/explanation-of-x264-tune +- https://stackoverflow.com/questions/33624016/why-sliced-thread-affect-so-much-on-realtime-encoding-using-ffmpeg-x264 +- https://codec.fandom.com/ru/wiki/X264_-_описание_ключей_кодирования +- https://html5test.com/ +- https://trac.ffmpeg.org/wiki/Capture/Webcam +- https://trac.ffmpeg.org/wiki/DirectShow +- https://stackoverflow.com/questions/53207692/libav-mjpeg-encoding-and-huffman-table +- https://github.com/tuupola/esp_video/blob/master/README.md +- https://github.com/leandromoreira/ffmpeg-libav-tutorial +- https://www.reddit.com/user/VeritablePornocopium/comments/okw130/ffmpeg_with_libfdk_aac_for_windows_x64/ +- https://slhck.info/video/2017/02/24/vbr-settings.html +- [HomeKit audio samples problem](https://superuser.com/questions/1290996/non-monotonous-dts-with-igndts-flag) diff --git a/scripts/README.md b/scripts/README.md index 5594915d..8abb0c75 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1,33 +1,14 @@ -## Versions +# Scripts -**PS.** Unfortunately, due to the dependency on `pion/webrtc/v4 v4.1.3`, had to upgrade go to `1.23`. Everything described below is not relevant. +This folder contains a script for building binaries for all platforms. -[Go 1.20](https://go.dev/doc/go1.20) is last version with support Windows 7 and macOS 10.13. -Go 1.21 support only Windows 10 and macOS 10.15. +The project has no `CGO` dependencies, so building is as simple as possible using the `go build` command. -So we will set `go 1.20` (minimum version) inside `go.mod` file. And will use env `GOTOOLCHAIN=go1.20.14` for building -`win32` and `mac_amd64` binaries. All other binaries will use latest go version. +The project has to use the latest versions of go due to dependencies on third-party go libraries. Such as `pion/webrtc` or `golang.org/x`. Unfortunately, this breaks compatibility with older versions of operating systems. -``` -github.com/miekg/dns v1.1.63 -golang.org/x/crypto v0.33.0 -golang.org/x/mod v0.20.0 // indirect -golang.org/x/net v0.35.0 // indirect -golang.org/x/sync v0.11.0 // indirect -golang.org/x/sys v0.30.0 // indirect -golang.org/x/tools v0.24.0 // indirect -``` +The project uses [UPX](https://github.com/upx/upx) to compress binaries for Linux. The project does not use compression for Windows due to false antivirus alarms. The project does not use compression for macOS due to broken result. -## Build - -- UPX-3.96 pack broken bin for `linux_mipsel` -- UPX-3.95 pack broken bin for `mac_amd64` -- UPX pack broken bin for `mac_arm64` -- UPX windows pack is recognised by anti-viruses as malicious -- `aarch64` = `arm64` -- `armv7` = `arm` - -## Go +## Useful commands ``` go get -u @@ -69,18 +50,20 @@ go list -deps .\cmd\go2rtc_rtsp\ ## Licenses - github.com/asticode/go-astits - MIT +- github.com/eclipse/paho.mqtt.golang - EPL-2.0 - github.com/expr-lang/expr - MIT - github.com/gorilla/websocket - BSD-2 - github.com/mattn/go-isatty - MIT - github.com/miekg/dns - BSD-3 -- github.com/pion/ice/v2 - MIT +- github.com/pion/dtls - MIT +- github.com/pion/ice - MIT - github.com/pion/interceptor - MIT - github.com/pion/rtcp - MIT - github.com/pion/rtp - MIT -- github.com/pion/sdp/v3 - MIT -- github.com/pion/srtp/v2 - MIT +- github.com/pion/sdp - MIT +- github.com/pion/srtp - MIT - github.com/pion/stun - MIT -- github.com/pion/webrtc/v3 - MIT +- github.com/pion/webrtc - MIT - github.com/rs/zerolog - MIT - github.com/sigurn/crc16 - MIT - github.com/sigurn/crc8 - MIT @@ -93,6 +76,11 @@ go list -deps .\cmd\go2rtc_rtsp\ - github.com/google/uuid - BSD-3 - github.com/kr/pretty - MIT - github.com/mattn/go-colorable - MIT +- github.com/pion/datachannel - MIT +- github.com/pion/logging - MIT +- github.com/pion/mdns - MIT +- github.com/pion/randutil - MIT +- github.com/pion/sctp - MIT - github.com/pmezard/go-difflib - ??? - github.com/wlynxg/anet - BSD-3 - golang.org/x/mod - BSD-3 diff --git a/website/.vitepress/config.js b/website/.vitepress/config.js new file mode 100644 index 00000000..e66ca806 --- /dev/null +++ b/website/.vitepress/config.js @@ -0,0 +1,147 @@ +import {defineConfig} from 'vitepress'; + +export default defineConfig({ + title: 'go2rtc', + themeConfig: { + nav: [ + {text: 'Home', link: '/'}, + ], + sidebar: [ + { + items: [ + {text: 'Installation', link: '/#installation'}, + {text: 'Configuration', link: '/#configuration'}, + {text: 'Security', link: '/#security'}, + ], + }, + { + text: 'Features', + items: [ + {text: 'Streaming input', link: '/#streaming-input'}, + {text: 'Streaming output', link: '/#streaming-output'}, + {text: 'Streaming ingest', link: '/#streaming-ingest'}, + {text: 'Two-way audio', link: '/#two-way-audio'}, + {text: 'Stream to camera', link: '/#stream-to-camera'}, + {text: 'Publish stream', link: '/#publish-stream'}, + {text: 'Preload stream', link: '/#preload-stream'}, + ], + collapsed: false, + }, + { + text: 'Codecs', + items: [ + {text: 'Codecs filters', link: '/#codecs-filters'}, + {text: 'Codecs madness', link: '/#codecs-madness'}, + {text: 'Built-in transcoding', link: '/#built-in-transcoding'}, + {text: 'Codecs negotiation', link: '/#codecs-negotiation'}, + ], + collapsed: true, + }, + { + text: 'Other', + items: [ + {text: 'Projects using go2rtc', link: '/#projects-using-go2rtc'}, + {text: 'Camera experience', link: '/#camera-experience'}, + {text: 'Tips', link: '/#tips'}, + ], + collapsed: true, + }, + { + text: 'Core modules', + items: [ + {text: 'app', link: '/internal/app/'}, + {text: 'api', link: '/internal/api/'}, + {text: 'streams', link: '/internal/streams/'}, + ], + collapsed: false, + }, + { + text: 'Main modules', + items: [ + {text: 'http', link: '/internal/http/'}, + {text: 'mjpeg', link: '/internal/mjpeg/'}, + {text: 'mp4', link: '/internal/mp4/'}, + {text: 'rtsp', link: '/internal/rtsp/'}, + {text: 'webrtc', link: '/internal/webrtc/'}, + ], + collapsed: false, + }, + { + text: 'Other modules', + items: [ + {text: 'hls', link: '/internal/hls/'}, + {text: 'homekit', link: '/internal/homekit/'}, + {text: 'onvif', link: '/internal/onvif/'}, + {text: 'rtmp', link: '/internal/rtmp/'}, + {text: 'webtorrent', link: '/internal/webtorrent/'}, + {text: 'wyoming', link: '/internal/wyoming/'}, + ], + collapsed: false, + }, + { + text: 'Script sources', + items: [ + {text: 'echo', link: '/internal/echo/'}, + {text: 'exec', link: '/internal/exec/'}, + {text: 'expr', link: '/internal/expr/'}, + {text: 'ffmpeg', link: '/internal/ffmpeg/'}, + ], + collapsed: false, + }, + { + text: 'Other sources', + items: [ + {text: 'alsa', link: '/internal/alsa/'}, + {text: 'bubble', link: '/internal/bubble/'}, + {text: 'doorbird', link: '/internal/doorbird/'}, + {text: 'dvrip', link: '/internal/dvrip/'}, + {text: 'eseecloud', link: '/internal/eseecloud/'}, + {text: 'flussonic', link: '/internal/flussonic/'}, + {text: 'gopro', link: '/internal/gopro/'}, + {text: 'isapi', link: '/internal/isapi/'}, + {text: 'ivideon', link: '/internal/ivideon/'}, + {text: 'hass', link: '/internal/hass/'}, + {text: 'mpegts', link: '/internal/mpegts/'}, + {text: 'multitrans', link: '/internal/multitrans/'}, + {text: 'nest', link: '/internal/nest/'}, + {text: 'ring', link: '/internal/ring/'}, + {text: 'roborock', link: '/internal/roborock/'}, + {text: 'tapo', link: '/internal/tapo/'}, + {text: 'tuya', link: '/internal/tuya/'}, + {text: 'v4l2', link: '/internal/v4l2/'}, + {text: 'wyze', link: '/internal/wyze/'}, + {text: 'xiaomi', link: '/internal/xiaomi/'}, + {text: 'yandex', link: '/internal/yandex/'}, + ], + collapsed: false, + }, + { + text: 'Helper modules', + items: [ + {text: 'debug', link: '/internal/debug/'}, + {text: 'ngrok', link: '/internal/ngrok/'}, + {text: 'pinggy', link: '/internal/pinggy/'}, + {text: 'srtp', link: '/internal/srtp/'}, + ], + collapsed: false, + }, + + ], + socialLinks: [ + {icon: "github", link: "https://github.com/AlexxIT/go2rtc"} + ], + outline: [2, 3], + search: {provider: 'local'}, + }, + + rewrites: { + 'README.md': 'index.md', + '(.*)/README.md': '(.*)/index.md', + }, + + srcDir: '..', + srcExclude: ['examples/', 'pkg/'], + + // cleanUrls: true, + ignoreDeadLinks: true, +}); diff --git a/website/README.md b/website/README.md new file mode 100644 index 00000000..81a2ad04 --- /dev/null +++ b/website/README.md @@ -0,0 +1,9 @@ +# WebSite + +These are the sources of the [go2rtc.org](https://go2rtc.org/) website. It's content published on GitHub Pages and is a mirror of [alexxit.github.io/go2rtc/](http://alexxit.github.io/go2rtc/). + +The site contains: + +- Project's documentation, which is compiled via [vitepress](https://github.com/vuejs/vitepress) from `README.md` files located in the root of the repository, as well as in the `internal` folder. +- Project's API in OpenAPI format, and the [Redoc](https://github.com/Redocly/redoc) viewer +- Project's assets (logo). diff --git a/website/api/index.html b/website/api/index.html index 65e87fa3..2f676782 100644 --- a/website/api/index.html +++ b/website/api/index.html @@ -1,7 +1,7 @@ - go2rtc - API + API | go2rtc @@ -13,7 +13,7 @@ - + \ No newline at end of file diff --git a/api/openapi.yaml b/website/api/openapi.yaml similarity index 100% rename from api/openapi.yaml rename to website/api/openapi.yaml diff --git a/website/favicon.ico b/website/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..aade0bf3438e35db84c61a249cbf299a3fb72a4b GIT binary patch literal 15086 zcmeI3OKes}6vr>LP@s>mwDx6dT1s1Al~)WlCXK~J!lts&8lsVCV9{V*xM&0kwbF!z z3nIn_8Wu(jN(h1r5)z@J9pYRdv5fqo40P;(%aW(x60+9A3ib`9V6im&f%W5B5Lh{J8XlY`|9;L zUT~R$FMdaV|G$cPsi~=nJReen$m1w;NlX(Xg4@I^=Wy@GztboD{9yh1NOJ*xxQ|jh ziCZ`qe1g~69zXW0+P?Lo+Vs&+>htY)RL9}J)o<7DI$=L>jqcLYics+c=Wrjkc7mOp zgexaruJMUE0rQJh$5ejmA(fZfsdCeQQF$3x)pHB3+rAJpeg`(N6(%R(o;noNHwZiU z!QQaC%f=0MCw_cDHmtp^!uSwo9^jrjlQi7+8=};AN=s+1NOl$c^d^k7`$@XFSeL7))Z&FJFoH2 znY+Y1ybJf(CqJk?@J<|s;U9mAVXye1_W1dLebyAe+5>*~{B5%HcQA*y4y!|9^Ot=U z7`*Tg)gRxzCvij!`uX4%Lz2(3ewp=?c?deN=@mEP5BP&>5PjKS`Q?JlfvmfN-CTbK zKd}>3JF$gL!RghqeudpXP{+{gH4owgxh!jeiJzE(_p!o`PrQR6Uj8}n!%3Ju5cxn( zFc#8Ffsa_%lkX;@IiZMKRwQ8vR{B#azzBZeru&u zPtY}WpYJC~m^C0s-$XyB?#s7w&CR6!eyDk~s6k^nx8pq*QhUJ8K@Jc@lfeftf)&hz z=m-Dhnt70SV%^XF?Lt2d+=q;3AGih!H3n>8bYeICkZ-!WPyDwd)@X8sy#_k)ACcdR z(2b2K!WbDZ`p}IHY+)0utWRJ8GuTY5QO+gTX{BySi|&z#jF;B55d~YKZ-RjY1Cx`1 z!Tqf+^7av;?Y68Gy(0XHyD`h^piR2pHgi42vck4>r~gAaBH(NWpzhy6YxpZXsAm0G z^AeiJA-?%Ltr9IYTH=4FrT>;IaZDZt+S=MuMC$75Vn|h0Rlc7{KN&|G#$$9=R#sLQ z7Z<;smzUR+m6g@1_Z_>_)6>60X3m^>97#z@`O#0LpNvBXy3mPkY+%d8#C>!oB_;he zefs$QO$)lQfh}x;p}f3&F4y{WLieNa1P`U9rL|z1X#2^@$-grfdT!Q4;her@Wo2r~ zk|pZp<;!j1oO@C9;4^bTY=rT>u&_|o*Vn7BckNPLU8nUoh->ObZ=e45KVS>j`}Tcn z_n~i)POuV_#HU~1*|Rg%n=4nUL+$OhJ-*{$7xDTI1wO_E@qzE;iI;u+*tV@LZcpse zo;rC`ef4FJI()ESUAp+-Z?EveSU)cC-7EGP2iK;**oEiyjb~KloKBUW)~*V(uBhi1 z>EDMp{$bC<;5v2xU*^OM135q(I{k-pH{009Hg-j@F9HU)16}BJ+QE0{9C5v&smYb| z_JiGVzjM>tR8H1wDnDn>C5dfwzL|$@pIwUkJv(Em9bfph z_}Mjf91shL+kq~0oA%u54mmv%`}pl=AN*nL!~Z8+ws`ViUhuum0sO;(JqJ1-h(W}Q ze{?$M8vfnlk9Z|+-D3Zp)hFX~An_j*f7A}Q93cL@@=w3t+cn3DfxHKU@L<{|=bZ<( zsm{)SzDm=AQqr{srepK~zMhrXsAuk)dOR;2Y8pU_X9vK}I=HQWpG*Tf;~@5A1I zJgof}dB^^X{jtu?wbTM-@*Eik3EQ3ZBZy$k?dA&+pec)~WOFETVr$xNM5trw@G@!&se*pK5)f)&*xj#-h)8f8oMK zs-dAlwYIj}(%9IjxaaK0STM?cU0W1=&tJHp|4yJ!b)CASx~~kVfq{GWbxTW&{@pwl z*E8fNpQP;j*kc^>;kvWx>5@+MYrRkQf13mN+9on`%mhs?~u}3 - - - - go2rtc - - - - -go2rtc -github.com/AlexxIT/go2rtc - - diff --git a/www/README.md b/www/README.md index e4d36cd2..6fd49ced 100644 --- a/www/README.md +++ b/www/README.md @@ -1,3 +1,49 @@ +# www + +This folder contains static HTTP and JS content that is embedded into the application during build. An external developer can use it as a basis for integrating go2rtc into their project or for developing a custom web interface for go2rtc. + +## HTTP API + +`www/stream.html` - universal viewer with support params in URL: + +- multiple streams on page `src=camera1&src=camera2...` +- stream technology autoselection `mode=webrtc,webrtc/tcp,mse,hls,mp4,mjpeg` +- stream technology comparison `src=camera1&mode=webrtc&mode=mse&mode=mp4` +- player width setting in pixels `width=320px` or percents `width=50%` + +`www/webrtc.html` - WebRTC viewer with support two way audio and params in URL: + +- `media=video+audio` - simple viewer +- `media=video+audio+microphone` - two way audio from camera +- `media=camera+microphone` - stream from browser +- `media=display+speaker` - stream from desktop + +## JavaScript API + +- You can write your viewer from the scratch +- You can extend the built-in viewer - `www/video-rtc.js` +- Check example - `www/video-stream.js` +- Check example - https://github.com/AlexxIT/WebRTC + +`video-rtc.js` features: + +- support technologies: + - WebRTC over UDP or TCP + - MSE or HLS or MP4 or MJPEG over WebSocket +- automatic selection best technology according on: + - codecs inside your stream + - current browser capabilities + - current network configuration +- automatic stop stream while browser or page not active +- automatic stop stream while player not inside page viewport +- automatic reconnection + +Technology selection based on priorities: + +1. Video and Audio better than just Video +2. H265 better than H264 +3. WebRTC better than MSE, than HLS, than MJPEG + ## Browser support [ECMAScript 2019 (ES10)](https://caniuse.com/?search=es10) supported by [iOS 12](https://en.wikipedia.org/wiki/IOS_12) (iPhone 5S, iPad Air, iPad Mini 2, etc.). @@ -8,86 +54,6 @@ But [ECMAScript 2017 (ES8)](https://caniuse.com/?search=es8) almost fine (`es6 + - Autoplay doesn't work for WebRTC in Safari [read more](https://developer.apple.com/documentation/webkit/delivering_video_content_for_safari/). -## HTML5 - -**1. Autoplay video tag** - -[Video auto play is not working](https://stackoverflow.com/questions/17994666/video-auto-play-is-not-working-in-safari-and-chrome-desktop-browser) - -> Recently many browsers can only autoplay the videos with sound off, so you'll need to add muted attribute to the video tag too - -```html - - -``` - -- https://developer.apple.com/documentation/webkit/delivering_video_content_for_safari/ - -**2. [Safari] pc.createOffer** - -Don't work in Desktop Safari: - -```js -pc.createOffer({offerToReceiveAudio: true, offerToReceiveVideo: true}) -``` - -Should be replaced with: - -```js -pc.addTransceiver('video', {direction: 'recvonly'}); -pc.addTransceiver('audio', {direction: 'recvonly'}); -pc.createOffer(); -``` - -**3. pc.ontrack** - -TODO - -```js -pc.ontrack = ev => { - const video = document.getElementById('video'); - - // when audio track not exist in Chrome - if (ev.streams.length === 0) return; - - // when audio track not exist in Firefox - if (ev.streams[0].id[0] === '{') return; - - // when stream already init - if (video.srcObject !== null) return; - - video.srcObject = ev.streams[0]; -} -``` - -## Chromecast 1 - -2023-02-02. Error: - -``` -InvalidStateError: Failed to execute 'addTransceiver' on 'RTCPeerConnection': This operation is only supported in 'unified-plan'. 'unified-plan' will become the default behavior in the future, but it is currently experimental. To try it out, construct the RTCPeerConnection with sdpSemantics:'unified-plan' present in the RTCConfiguration argument. -``` - -User-Agent: `Mozilla/5.0 (X11; Linux armv7l) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.47 Safari/537.36 CrKey/1.36.159268` - -https://webrtc.org/getting-started/unified-plan-transition-guide?hl=en - -## Web Icons - -[Favicon checker](https://realfavicongenerator.net/), skip: - -- Windows 8 and 10 (`browserconfig.xml`) -- Mac OS X El Capitan Safari - -```html - - - - - - -``` - ## Useful links - https://www.webrtc-experiment.com/DetectRTC/