JustOnAir docs
For AI agents llms.txt OpenAPI Dashboard
View as Markdown

Quickstart

Create a stream, send a test picture with ffmpeg or OBS, and watch it in the hosted player. About five minutes.

You need an API key and a terminal. For step 3 you need either ffmpeg or OBS Studio.

1. Set your API key

Create a key in the dashboard under API keys (app.justonair.com). It starts with joa_live_ and is shown once.

Shell
export JOA_API_KEY="joa_live_..."

2. Create a stream

Shell
curl https://api.justonair.com/v1/streams \
  -H "Authorization: Bearer $JOA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "My first stream"}'

The answer (shortened; the secrets are replaced here):

JSON
{
  "id": "str_e1bzk3dxw9z9allei6n7",
  "object": "stream",
  "name": "My first stream",
  "status": "pending",
  "rtmp_url": "rtmp://ingest-1.justonair.com:1935/abr-basic",
  "stream_key": "str_e1bzk3dxw9z9allei6n7?key=...",
  "whip_url": "https://ingest-1.justonair.com:3334/abr-basic/str_e1bzk3dxw9z9allei6n7?direction=whip&key=...",
  "embed_url": "https://play.joacdn.com/str_e1bzk3dxw9z9allei6n7",
  "playback_url": "https://live.joacdn.com/bcdn_token=.../str_e1bzk3dxw9z9allei6n7/master.m3u8",
  "renditions": ["source", "480p"],
  "reservation_expires_in_seconds": 1800
}

The stream now waits up to 30 minutes for video. If nothing connects in that time it expires, and you create a new one.

3. Send video

With ffmpeg (no camera needed)

This sends a moving test picture with a tone, at 720p, with the settings JustOnAir wants: H.264, a keyframe every 2 seconds, under 6 Mbps.

Shell
RTMP_URL="rtmp://ingest-1.justonair.com:1935/abr-basic"   # rtmp_url from step 2
STREAM_KEY="str_e1bzk3dxw9z9allei6n7?key=..."            # stream_key from step 2

ffmpeg -re \
  -f lavfi -i "testsrc2=size=1280x720:rate=30" \
  -f lavfi -i "sine=frequency=440:sample_rate=48000" \
  -c:v libx264 -preset veryfast -tune zerolatency -b:v 2500k \
  -g 60 -keyint_min 60 -sc_threshold 0 -pix_fmt yuv420p \
  -c:a aac -b:a 128k -ar 48000 \
  -f flv "$RTMP_URL/$STREAM_KEY"

Keep the quotes: the stream key contains a ?.

With OBS

In Settings → Stream, choose Custom, then:

OBS fieldValue
Serverrtmp_url
Stream Keystream_key

In Settings → Output (Advanced mode): Encoder x264 or your hardware H.264 encoder, Bitrate up to 6000 Kbps, Keyframe Interval 2 s. OBS's default of "0 (auto)" sends a keyframe only every 8 seconds or so, which makes quality switching stutter. Then press Start Streaming.

4. Watch it

Open embed_url in a browser. Before the video arrives it shows a waiting screen; it switches to the picture by itself, usually 10–20 seconds after you start sending. To put the player on a page:

HTML
<iframe src="https://play.joacdn.com/str_e1bzk3dxw9z9allei6n7"
  allow="autoplay; fullscreen; picture-in-picture" allowfullscreen
  style="aspect-ratio:16/9;width:100%;border:0"></iframe>

5. Follow it and end it

Shell
curl https://api.justonair.com/v1/streams/str_e1bzk3dxw9z9allei6n7 \
  -H "Authorization: Bearer $JOA_API_KEY"

status becomes live as soon as the publisher is accepted. ingest shows what is arriving (size, bitrate, keyframe interval) and cost what the stream has cost so far.

To end it:

Shell
curl -X DELETE https://api.justonair.com/v1/streams/str_e1bzk3dxw9z9allei6n7 \
  -H "Authorization: Bearer $JOA_API_KEY"

The publisher is disconnected within seconds, viewers see the end screen, and a few minutes later recording.status is ready: download the MP4.

Next