Control an NDI® recording with Companion and the HTTP API | Apex

To control recording of an NDI® source with Bitfocus Companion, use Generic HTTP Requests and the Timecode Recorder API: POST /start_record starts, POST /stop_record stops and GET /status reads status. Configure separate buttons to keep each command explicit and check its result.

Prepare the Recorder and network

Open Timecode Recorder, select a source and click Connect. Wait for at least one received frame; a connection alone is insufficient for an API start. Check sound before the take too. The default port is 8088. In the API panel, note the actual displayed base URL. After changing the port, use Apply and update your Companion configuration.

If Companion runs on the same Mac, http://127.0.0.1:8088 works with the default port. On another computer, replace it with the Recorder Mac’s LAN address. 127.0.0.1 always refers to the machine sending the request.

Keep this API on a trusted network, without Internet exposure. Automatic responds on the Mac’s network interfaces. Selecting a card can reject a request with HTTP 403 when its address does not match, but this filter is neither authentication nor strong isolation. Restrict network access to authorised machines.

Create the Generic HTTP Requests connection

1. In Companion, add a connection using Generic HTTP Requests. Consult the official Bitfocus module documentation for your version’s fields.
2. Set Base URL to the Recorder URL without a command path, for example http://127.0.0.1:8088. Alternatively, leave it empty and enter full URLs in each action.
3. Create a START REC button. On press, add a POST request action with the full URL http://127.0.0.1:8088/start_record, adapted to your host. Leave the body empty; no JSON is required.
4. Create STOP REC in the same way, using POST to http://127.0.0.1:8088/stop_record.
5. Create a third, read-only STATUS button using GET to http://127.0.0.1:8088/status. A full URL overrides Base URL: update all three actions if the address changes.

Understand what each request confirms

To isolate a problem before using Companion, run these commands separately in a terminal on the Recorder Mac, allowing a short take between Start and Stop:

curl --fail-with-body http://127.0.0.1:8088/status
curl --fail-with-body -X POST http://127.0.0.1:8088/start_record
curl --fail-with-body -X POST http://127.0.0.1:8088/stop_record

A recording command sent with GET returns 405. An invalid parameter or missing source can produce 400; an address rejection, 403. Read the response instead of treating every HTTP exchange as success.

Common mistake: retrying Start after silence

Avoid automatic retries: another Start can replace an active recording. If a response is missing, inspect the application and Status first. A button coloured on press indicates a requested action; to show actual state, configure response reading and interpretation separately. Keep manual controls accessible.

Find and check the file

An API start writes to ~/Movies/NDI_YYYYMMDD-HHMMSS.mov, independently of the folder and filename entered in Recording. After Stop, open that file and check picture, sound and duration. Begin with a short test, followed by a network-loss check with no useful take in progress. WebRTC helps observe the picture but does not confirm complete MOV writing.

NDI® is a registered trademark of Vizrt NDI AB.