tribes-plugin-sender/docs/API.md

Sender Public API

Sender exposes two public control surfaces:

1. Plugin management methods for remote/admin orchestration, including Legion.
2. TribeOne.TribesPlugin.Sender.LocalStreams for IEx and local no-Legion operation on the node.

Local stream control from IEx

Use TribeOne.TribesPlugin.Sender.LocalStreams when you are on a node and want to operate Sender without Legion:

{:ok, live} = TribeOne.TribesPlugin.Sender.LocalStreams.start_origin()
TribeOne.TribesPlugin.Sender.LocalStreams.status()
TribeOne.TribesPlugin.Sender.LocalStreams.stop(live)

start_origin/1 requires the local Tribes node identity to exist. It reads the node pubkey with Tribes.Identity.node_pubkey/0, upserts a local tribes_origin media endpoint, then starts the normal stream.start origin lifecycle.

To generate a test stream with local ffmpeg and push it to the node's RTMP listener:

{:ok, live} = TribeOne.TribesPlugin.Sender.LocalStreams.start_origin(push_test?: true)

The generated publisher uses MuonTrap and runs under Sender supervision. Stop it without stopping the stream:

TribeOne.TribesPlugin.Sender.LocalStreams.stop_test_video(live)

Use a finite test-video duration if desired:

{:ok, live} = TribeOne.TribesPlugin.Sender.LocalStreams.start_origin(push_test?: true, duration: 30)

Useful defaults:

• node-side RTMP listener: rtmp://0.0.0.0:1935/live/source
• local ffmpeg push URL: rtmp://127.0.0.1:1935/live/source
• advertised RTMP ingest URL: rtmp://localhost:1935/live/source
• HLS base URL: http://localhost:4000/sender/hls

Common overrides:

TribeOne.TribesPlugin.Sender.LocalStreams.start_origin(
  input_url: "rtmp://0.0.0.0:1936/live/source",
  push_url: "rtmp://127.0.0.1:1936/live/source",
  hls_base_url: "https://example.test/sender/hls",
  spool_root: "/var/lib/tribes/sender/hls"
)

You can also start only the generated publisher after opening a stream:

{:ok, test_video} = TribeOne.TribesPlugin.Sender.LocalStreams.push_test_video(duration: 10)
TribeOne.TribesPlugin.Sender.LocalStreams.stop_test_video(test_video["pid"])

Remote management methods

Remote orchestration should continue using Sender's plugin management methods through Tribes' admin management API. The primary methods are:

• capabilities
• stream.get_default
• stream.ensure_default
• stream.update_default
• stream_key.create
• media_endpoints.upsert
• renditions.upsert
• stream.start
• stream.stop
• stream.status
• endpoint_snapshots.report

TribeOne.TribesPlugin.Sender.LocalStreams composes these same management handlers locally. It is not a separate remote command API for running arbitrary ffmpeg commands.