Repository navigation
Playing Streams
Outpace has two HTTP interfaces for playback:
- the native API (
/streams/...,/vod/...). It is always on, and it's the one to use for players, media servers and playlist tools; - the AceStream-compatible API (
/ace/...,/server/api). It is off by default. Turn it on for apps and add-ons written for the original engine.
Both serve the same streams. A stream opened through one interface is shared with viewers on the other.
Examples use http://127.0.0.1:6878 and the placeholder id
0123456789abcdef0123456789abcdef01234567.
| Input | Native form | Notes |
|---|---|---|
| Content id (40 hex characters) |
/streams/ace/<id> or /streams/ace/cid:<id>
|
The usual AceStream id. Resolved through the AceStream catalog. |
| Infohash | /streams/ace/ih:<infohash> |
A swarm hash. Plays only if Outpace can find a verified descriptor for it (its own broadcasts, ones seen before, or the catalog). Otherwise 422. |
Transport file (.acelive / .torrent URL) |
via the compat url= selector or outpace play <url>
|
Fetched over HTTP(S) with a 1 MiB limit, no redirects, and private addresses refused. |
Magnet (magnet:?xt=urn:btih:...) |
via compat magnet= or outpace play
|
Reduced to its infohash, then treated like an infohash. BitTorrent v2 magnets aren't supported. |
| Local descriptor | /streams/ace/local%3A<alias> |
Private Peer Mode only. |
Upgrading from an early build? A bare 40-hex id on
/streams/ace/means a content id. Older playlists that used bare infohashes there must switch toih:<infohash>. There is no silent fallback from one to the other.
Content ids are case-insensitive. Outpace lowercases them, and the bare and cid: forms share
one session.
| URL | Returns |
|---|---|
GET /streams/ace/<id> |
Continuous MPEG-TS (video/mp2t). Includes Icy-Name when the stream has a title. |
GET /streams/ace/<id>.ts |
The same, written explicitly. |
GET /streams/ace/<id>.m3u8 |
A live HLS playlist. Segments are /streams/ace/<id>/seg/<n>.ts. See HLS Output. |
Opening any of these starts the stream, or joins it if it's already running. Every viewer of one source shares a single download.
vlc "http://127.0.0.1:6878/streams/ace/0123456789abcdef0123456789abcdef01234567"
mpv "http://127.0.0.1:6878/streams/ace/0123456789abcdef0123456789abcdef01234567.m3u8"
ffmpeg -i "http://127.0.0.1:6878/streams/ace/0123456789abcdef0123456789abcdef01234567" \
-c copy -t 60 clip.tscurl http://127.0.0.1:6878/streams
curl http://127.0.0.1:6878/streams/ace/0123456789abcdef0123456789abcdef01234567/statusA status response looks like this:
{
"network": "ace",
"id": "cid:0123456789abcdef0123456789abcdef01234567",
"clients": 1,
"peers": 4,
"bitrate": 2450000,
"buffer_ms": 6200,
"uploaded": 1048576,
"peers_served": 2,
"recovery": {"upstream_reconnects": 0, "stale_teardowns": 0,
"skipped_evicted_gaps": 0, "signature_rejects": 0, "active_upstreams": 4},
"metadata": {"title": "My Channel", "bitrate": 2450000, "categories": ["other"]}
}| Field | Meaning |
|---|---|
clients |
Direct MPEG-TS viewers. HLS viewers don't add to it. |
peers |
Connected upstream peers. |
bitrate |
Measured incoming media rate in bits per second, over about five seconds. |
buffer_ms |
Media queued on the server. It isn't the player's buffer and can correctly be near zero. |
uploaded, peers_served
|
What you have uploaded to other peers. |
recovery |
Counters for reconnects, pool rebuilds, skipped gaps and rejected pieces. Rising numbers mean a struggling swarm. |
metadata |
Title, advertised bitrate (bits/s) and categories from the descriptor, or null, null and []. |
normalization |
Audio-conversion state when live audio normalisation is on, otherwise null. |
The status route never starts a stream; it returns 404 when the stream isn't running. Use it
(and /streams) for monitoring. Don't poll a playback URL as a health check, because that
starts or keeps alive a real stream.
Closing the player is enough. When no viewer, HLS client or lease is left, the stream is torn down after a 30-second grace period, which lets a player reconnect without starting over.
To stop a stream immediately for everyone watching it:
curl -X DELETE http://127.0.0.1:6878/streams/ace/0123456789abcdef0123456789abcdef01234567This returns 204, or 404 if the stream wasn't running.
| Status | Meaning |
|---|---|
400 |
A malformed cid: or ih: selector. |
404 |
Unknown network or invalid id. For a segment: not produced yet, or already outside the window. |
422 |
The input couldn't be turned into a playable descriptor, for example an infohash with no verified descriptor. The body gives the reason. |
503 + Retry-After: 1
|
HLS not ready within the startup timeout, the session cap reached, or audio conversion temporarily unavailable. |
Most AceStream content is live: a continuous signed stream with no fixed length. Outpace follows the live edge and keeps only a short window.
VOD content is a single file with a fixed length and per-piece hashes. Outpace verifies every piece before sending it:
| URL | Returns |
|---|---|
GET /vod/ace/cid:<id> |
The whole file, with Content-Length and Accept-Ranges: bytes. Single byte ranges (206) work, so players can seek. An unsatisfiable range gives 416. |
GET /vod/ace/cid:<id>/manifest.m3u8 |
A static HLS playlist for the file. |
GET /vod/ace/cid:<id>/seg/<n>.ts |
One verified HLS segment. |
mpv "http://127.0.0.1:6878/vod/ace/cid:0123456789abcdef0123456789abcdef01234567"
outpace play --vod acestream://0123456789abcdef0123456789abcdef01234567 > movie.mp4Multi-file VOD isn't supported and fails with a clear error. VOD isn't available through the compatibility API.
outpace play streams to standard output without a server. Progress and errors go to standard
error, so piping is safe:
outpace play acestream://0123456789abcdef0123456789abcdef01234567 | vlc -
outpace play "acestream:?content_id=0123456789abcdef0123456789abcdef01234567" > live.ts
outpace play https://example.com/channel.acelive | mpv -
outpace play --peer 192.0.2.10:8621 acestream://0123456789abcdef0123456789abcdef01234567 > live.ts-
--voddownloads and verifies a VOD file. -
--peer IP:PORTadds a bootstrap peer. You can repeat it. - Infohash and magnet inputs need a verified descriptor from the catalog. A one-shot process has no local history, so they fail if the catalog can't help.
Turn it on with OUTPACE_ACE_COMPAT=1 and restart. With it off, every route below returns
404.
http://127.0.0.1:6878/ace/getstream?id=0123456789abcdef0123456789abcdef01234567
http://127.0.0.1:6878/ace/manifest.m3u8?id=0123456789abcdef0123456789abcdef01234567
-
getstreamwithoutformat(or withformat=) returns MPEG-TS directly. -
manifest.m3u8redirects (302) to a stable, tokenised HLS playlist.
Selectors are tried in this order: content_id, infohash, id (an alias for content_id),
url, magnet. URL-encode url= and magnet= values.
Many apps ask for format=json, then use the URLs they get back:
curl "http://127.0.0.1:6878/ace/getstream?content_id=0123456789abcdef0123456789abcdef01234567&format=json"{"response": {
"playback_url": "http://127.0.0.1:6878/ace/r/.../...",
"stat_url": "http://127.0.0.1:6878/ace/stat/.../...",
"command_url": "http://127.0.0.1:6878/ace/cmd/.../...",
"infohash": "...", "playback_session_id": "...",
"is_live": 1, "is_encrypted": 0, "metadata": {...}},
"error": null}- Open
playback_urlto play. Readstat_urlfor statistics:speed_downandspeed_upare in KiB/s. - Stop with
command_url?method=stop. - Always check both the HTTP status and the JSON
errorfield. Most errors come back as HTTP200withresponse: null. - Treat the returned URLs as opaque. Don't build URLs from
infohashorplayback_session_id. - A TS
format=jsonrequest doesn't start the stream; openingplayback_urldoes. An HLSformat=jsonrequest starts it straight away.
/server/api?method=... and /webui/api/service?method=... answer
{"result": ..., "error": ...}:
| Method | Returns |
|---|---|
get_version |
Outpace's version (not an AceStream engine version). |
get_status |
dl when any stream is active, otherwise idle, plus session counts. |
get_network_connection_status |
Registered networks. Not a real connectivity test. |
analyze_content |
Whether an id is live and whether it's encrypted, without joining the swarm. |
get_content_id |
Echoes the content id you passed. It can't look one up from an infohash. |
get_media_files |
One synthetic file entry. Live entries report mime: video/mp2t. |
Each format=json or HLS request creates a lease:
- A lease expires six hours after it is created. Using it doesn't extend it.
- At most 4096 leases are kept; the oldest go first.
-
method=stopends that lease only. Other viewers keep playing. - Leases live in memory, so a restart invalidates them. The app has to request new URLs.
Once no lease or viewer holds a stream, it is torn down after the usual 30-second grace period.
There is no premium or encrypted content, no accounts, no web UI or remote control, no search,
channel lists or EPG, no file selection beyond the single file (_idx=0), no seeking in the
original engine's sense, and no VOD. Outpace adds its own timeshift commands
instead.
The compatibility API builds returned URLs from http:// plus the request's Host header. It
ignores X-Forwarded-* and Forwarded, and it never returns HTTPS. If clients reach Outpace
through TLS termination or a sub-path, the returned URLs won't work. See
Deployment.
| Client | How it connects | Status |
|---|---|---|
| VLC | Native URL or /ace/getstream?id=
|
Used in the documented examples. |
| mpv, ffmpeg, ffplay | Native TS or HLS URL | Plain HTTP TS/HLS consumers. Expected to work, but not separately tested. |
| Jellyfin and other IPTV-style media servers | Native URL in an M3U playlist | Supported integration target. |
| Dispatcharr | Native URL as the channel's media URL | Covered by local compatibility tests. |
| acexy | Compat JSON handshake, playback_url, stop command |
Covered by local compatibility tests. |
| Acestream-Manager | Compat health check, stats, TS/HLS proxy | Covered by local compatibility tests (search excluded). |
| Apps built on the public AceStream Android SDK | Compat /ace/* and /server/api
|
SDK request quirks are handled: duplicated selectors, stream_id=-1, api_version=2. |
Kodi and other add-ons using /ace/getstream
|
Compat API | Likely to work if they stick to the supported routes. Not tested. |
"Covered by local tests" means the client's requests were reproduced offline. It doesn't guarantee playback quality with every stream. For a playlist entry, prefer the plain native URL; it needs no handshake.
- HLS Output: segment and startup settings, audio, end of stream.
- Timeshift: rewinding compatibility HLS viewers.
- Managed HLS Origins: descriptors that point at an HLS server.
- Troubleshooting: slow starts, stalls and errors.
This wiki is generated from docs/wiki/ in the main repository. To fix or improve a page, open a pull request there; the wiki is republished automatically when it merges, and edits made in the wiki web UI are overwritten.
Start
Watching
Publishing and peers
- Broadcasting
- Seeding and Peers
- Engine Camouflage
- NAT and Port Mapping
- Private Peer Mode
- Outbound Proxy
Running it
- Deployment
- Routers and Small Devices
- Migrating from AceStream Engine
- Support Sources and Operations
- Troubleshooting
- Releases and Versions
Success stories