User guide

What it does

Newsroom turns a video from your Media Library into versions ready for publishing:

The new file is added to your Media Library next to the original. The original is never changed.

It can also make vertical news reels from your articles, with a voiceover, captions, your branding and your sponsor. See Making news reels.

How to use it

1. Open the video in the Media Library, or in the post you're editing.
2. Choose the version you want, for example Make vertical version.
3. Carry on working. The status shows Queued, then Processing, then Ready.
4. When it says Ready, the new file is in the Media Library.

Short clips are usually ready quickly; long or 4K videos take longer. If other videos from your newsroom are already processing, yours waits its turn and starts automatically. Processing stops after 30 minutes.

Making news reels

With the Newsroom Video plugin, Newsroom also makes vertical news videos from your published articles. Each one has an AI-written script read by an AI voice, the article's featured image as the background, captions, your logo and colours, and, if you have one, the current sponsor. Reels are made on our servers, so nobody has to keep a browser tab open, and they always come out as MP4: 1080×1920, ready for Reels, Shorts and TikTok.

Example 1: a video for one story

1. In WordPress, open Newsroom Video → Generate Video.
2. Leave the date filter on Today and tick one article, e.g. Council approves new library for Romford. The length box changes to your single-story default, such as 22 seconds.
3. Click Generate Script. Read the script and caption and correct anything, especially names, places and anything legal. Then click Next: Render Video.
4. On the render page, change the per-video controls if you want to, e.g. a bigger caption size, or the image panning right to left. Then click Render Vertical Video.
5. The status box shows the reel's progress. You can leave the page at any point. When it's done, the preview, a download button and the OnlySocial box appear.

What the status box shows on a quiet day:

Sending the video to the Newsroom Video service…
Queued on the Newsroom Video service: 1st in line, starting now. You can leave this page.
Rendering on the server: 35%. You can leave this page.
Rendering on the server: 80%. You can leave this page.
Finished. Saving the video to WordPress…
Video saved as MP4.

A reel takes roughly twice its own length to make. A 22-second story is usually ready in under a minute, and a 45-second bulletin in about a minute and a half. If other videos are waiting, yours queues first and the status box shows its place in line.

Example 2: a bulletin of three stories

Tick three articles instead of one (up to five are allowed). The length suggestion rises to 45 seconds, and the script covers each story in turn. In the video, each article gets its own scene with its own image and headline, and each scene lasts about as long as that story's part of the script. Everything else works as in Example 1.

Example 3: a video made automatically when an article is published

1. Write the article as usual. In the AI News Video box on the edit screen, leave Generate an AI video when this article is first published ticked. Untick it for articles that shouldn't get a video.
2. Publish. WordPress writes the script and voiceover, then sends the reel to our servers.
3. Follow it in Newsroom Video → Rendering Queue. The article shows Server Rendering, with notes like Queued on the Newsroom Video service (2 in line) or Rendering on the Newsroom Video service (45%), and then Completed.
4. If automatic OnlySocial posting is set up, the finished video goes out to your chosen accounts as well.

Automatic videos skip the script review. That's fine for routine stories, but for court cases, police appeals and allegations, untick the box and make the video yourself (Example 1), so that someone reads the script first.

Example 4: a video for every story today

On Generate Video, tick Create and publish a separate video for every article shown by this filter. The button becomes Create & Publish 6 Videos, or however many articles the filter shows. Each article gets its own reel, queued together. The service takes the videos one after another, so a batch of six takes several minutes. Other newsrooms' videos aren't held up meanwhile, because newsrooms take turns.

Example 5: landscape and square versions, a thumbnail and captions

For YouTube, Facebook or your own website you may want a landscape copy of each reel too. In Settings → Rendering → Also make, tick what you want with every vertical video:

• Landscape 16:9 video (1920×1080), for YouTube, Facebook and websites;
• Square video (1080×1080), for feeds;
• Thumbnail image, a JPEG of the first story;
• Caption files (.srt and .vtt), for platforms that show their own subtitles, such as YouTube.

Render as usual. When the reel is saved, buttons under the preview download each extra file, and the extra videos appear in the OnlySocial Video file list. They're all made from the same script, voiceover and settings, and the layout fits each shape. Automatic videos (Example 3) get the extras too.

Two more settings in the same place:

• Voiceover loudness evens out volume between videos. The default, −14 LUFS, is what Instagram, TikTok, YouTube and Facebook aim for, so your reels aren't turned down or left quiet.
• Maximum video length stops a video that's too long for where you post it. For example, set 90 if you post Facebook Reels. It's checked before the video is made, so a refused video costs nothing. Platforms change their limits, so check theirs.

Image motion also has Zoom in, Zoom out and Alternate (in on one story, out on the next), in Settings and on the render page.

How much allowance a reel uses

A reel counts the whole finished video, start and end screens included. For example:

At that length, the Starter plan's 10 hours is about 730 reels a month, and Pro's 50 hours over 3,600. Reels that fail don't count.

Each extra video format counts the same again: a 49-second reel in vertical and landscape uses 98 seconds. Thumbnails and caption files are free.

Setting it up (site administrators)

1. Install version 3.0 or later of the Newsroom Video plugin (2.10 for vertical videos only).
2. Go to Newsroom Video → Settings → Rendering. Set Render videos to On the Newsroom Video service, enter the service address (it starts https://) and paste your API key. Then save.
3. Open System Status. Video renderer should say something like Newsroom Video service, connected (pro plan, 2,950 of 3,000 minutes left this month).

The service downloads each reel's voiceover and images from your website, so:

• your site needs https://;
• it must be reachable from the internet. A staging site behind a password won't work;
• if you use a firewall or bot protection such as Cloudflare or Wordfence, it must let requests with the user agent NewsroomVideoRenderer/1.0 through.

Rendering in the browser instead. Set Render videos to In this browser and videos are made in the editor's browser tab, as in earlier versions. That uses none of your allowance, but the tab must stay open until the video is saved, automatic videos wait for someone to open the browser worker (unless your web server has FFmpeg), and some browsers produce WebM rather than MP4. On the render page you can also use Render in this browser instead for a single video. If the service address or key is missing, the plugin uses the browser automatically.

If a reel goes wrong

Files you can use

Plans and limits

The monthly allowance is shared by everyone in your newsroom. It's the total length of the videos you've processed, and it resets on the 1st of each month (UTC). Thumbnails count as one second, and videos that fail to process don't count at all.

The queue and priority processing

Newsrooms take turns: when several are waiting, each gets one video started before anyone gets a second. A newsroom that sends a big batch therefore waits for its own videos, not everyone else's.

Newsrooms with priority processing, an annual add-on or part of some plans, go first, taking turns with each other. A standard video that has waited a while is moved up to go alongside them, so it is never held back for long. Your account page shows which you have, and how long your recent videos waited.

Tips for good results

• Vertical and square versions crop the picture. They keep the centre of the shot and cut off the sides of a landscape video. Keep your subject in the middle, or film in portrait if you know you need a vertical video.
• Trim before you process. It's quicker and uses less of your allowance.
• Thumbnails are picked automatically from the first few seconds. For a particular moment, trim the video to start there first.
• Subtitles and extra audio tracks are not carried over. Only the main picture and the first audio track are kept.

Privacy and source protection

• Hidden information is removed from every processed file, including GPS location, camera and phone model, serial numbers and editing history.
• Copies are deleted from the service. The upload is deleted as soon as it has been processed, and the result once Newsroom has saved it, always within 24 hours.
• Videos are processed on our own servers and are never passed to a third-party processing or AI service.

Only the new file is cleaned. The original you uploaded to WordPress still has its metadata, so publish the processed version.

If something goes wrong

Checking your usage

Site administrators can see this month's allowance, daily and monthly history, recent jobs and the account's API keys on the Account page. Sign in with the email address registered for your newsroom and one of its API keys.

Programs can read the same headline figures from GET /v1/usage (see below).

We also email that address when your newsroom has used 80% of the month's allowance, again at 100%, and a week before one of your API keys expires.

API reference

Every /v1 call needs the header Authorization: Bearer nr_live_…. Make calls from your server, never from browser JavaScript. Read-only keys can look at jobs, downloads, usage and the webhook, but can't create, delete or change anything. A key may have an end date: in its last two weeks, responses include an api_key_expiring warning, so put the replacement key in your settings before then. Errors look like {"detail": "<code>", "message": "…", "docs_url": "…", "request_id": "…"}: switch on detail, and show or log the rest.

Headers worth sending

• Idempotency-Key on POST /v1/jobs: a value unique to the video and preset, such as attachment-123-mp4. Reuse it when you retry a failed or timed-out upload, and you get the original job back (with Idempotent-Replayed: true) instead of a second, billed job. A key that was used for a different preset returns 422 idempotency_key_reused.
• User-Agent naming your plugin and version, such as NewsroomVideo-WP/2.9.0 WordPress/6.6, so we can tell you before a change affects the version you run.
• X-Request-Id (optional): your own id for the call, 8 to 128 letters, digits, ., _, : or -. Every response carries one either way. Quote it when you contact support.

Warnings and changes

Every /v1 JSON response has a warnings array, usually empty. Show any entries to the site admin. Today it reports quota_nearly_used once 80% of the allowance is used. If something you use is going to be retired, you get a deprecated warning plus Deprecation and Sunset headers months beforehand. We only ever add to /v1, so ignore fields you don't recognise. Changes are listed in the changelog.

News reels

POST /v1/renders with a JSON body makes a 1080×1920 MP4 news reel: a voiceover, one to five article headlines and images, captions from the script, your logo and colours, an optional sponsor and start and end screens. The Newsroom Video plugin sends this for you. Images and the voiceover are given as https:// addresses we can download (public sites only), or small images inline as data: URLs. The body is limited to 1 MB. Follow the job with GET /v1/jobs/{id} and download it as usual. A reel is billed by its finished length, start and end screens included.

A full manifest. Only audio_url, script and articles (each with a title) are required; the rest use the plugin's defaults:

{
  "audio_url": "https://news.example/wp-content/uploads/newsroom-video/nrv_1730113200.mp3",
  "script": "The Riverside Daily News Update. Councillors have approved a new library for Romford…",
  "story_scripts": ["Councillors have approved a new library for Romford…", "Step-free access opens at Hornchurch…"],
  "articles": [
    { "title": "Council approves new library for Romford", "category": "Council", "image_url": "https://news.example/wp-content/uploads/2026/10/library.jpg" },
    { "title": "Hornchurch station step-free access opens", "category": "Transport", "image_url": "https://news.example/wp-content/uploads/2026/10/station.jpg" }
  ],
  "logo_url": "https://news.example/wp-content/uploads/logo.png", "logo_size_percent": 19, "logo_white_bg": true,
  "brand_colour": "#0b4f9c", "banner_text_colour": "#ffffff", "title_banner_opacity": 100,
  "caption_font_size": 86, "caption_bg_opacity": 74, "caption_advance": 0.35,
  "image_motion": "pan_left_right",
  "show_ai_label": true, "ai_label_text": "Generated by AI",
  "start_screen_url": "https://news.example/wp-content/uploads/start.png", "start_screen_duration": 2.5,
  "end_screen_url": "https://news.example/wp-content/uploads/end.png", "end_screen_duration": 2.5,
  "audio_tail_padding": 3.5,
  "sponsor": { "company_name": "Acme Bakery", "text": "Fresh bread daily", "logo_url": "https://news.example/wp-content/uploads/acme.png" },
  "outputs": ["vertical", "landscape", "thumbnail", "captions_srt", "captions_vtt"],
  "loudness_lufs": -14,
  "max_duration_seconds": 90
}

• outputs: what to make, at least one video. vertical (1080×1920, the default), landscape (1920×1080), square (1080×1080), thumbnail (JPEG), captions_srt and captions_vtt. The first video listed is the main one. Each video is billed for its length; thumbnails and captions are free.
• loudness_lufs: normalise the voiceover, e.g. −14 for social media. Leave it out to keep it as it is.
• max_duration_seconds: refuse a video longer than this before rendering, unbilled (job error duration_too_long).
• image_motion: auto, static, the four pans, zoom_in, zoom_out or alternate.

curl -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: reel-nrv_1730113200" \
     --data @reel.json "https://this-server/v1/renders"
# {"id":"5c1e…","status":"queued","preset":"news_reel","preset_version":1,"status_url":"/v1/jobs/5c1e…","warnings":[]}

curl -H "Authorization: Bearer $KEY" https://this-server/v1/jobs/5c1e…
# {"id":"5c1e…","status":"queued","queue_position":2,"estimated_start_seconds":40,"progress":null,…}
# {"id":"5c1e…","status":"processing","progress":45,…}
# {"id":"5c1e…","status":"complete","progress":100,"duration_seconds":48.5,"billable_seconds":98,"download_url":"/v1/jobs/5c1e…/download",
#  "outputs":[{"name":"vertical","media_type":"video/mp4","bytes":9120345,"width":1080,"height":1920,"download_url":"/v1/jobs/5c1e…/download?output=vertical"},
#             {"name":"landscape",…}, {"name":"thumbnail",…}, {"name":"captions_srt",…}, {"name":"captions_vtt",…}],…}

curl -H "Authorization: Bearer $KEY" -o reel.mp4 https://this-server/v1/jobs/5c1e…/download
curl -H "Authorization: Bearer $KEY" -o reel-landscape.mp4 "https://this-server/v1/jobs/5c1e…/download?output=landscape"
curl -H "Authorization: Bearer $KEY" -o reel.srt "https://this-server/v1/jobs/5c1e…/download?output=captions_srt"

A mistake in the manifest is reported straight away, naming the field:

# {"detail":"invalid_manifest","message":"brand_colour must be a colour like #0b4f9c","docs_url":"…/guide#errors","request_id":"…"}

The same from PHP, with the example client (NewsroomFfmpegClient.php):

$api = new NewsroomFfmpegClient('https://this-server', $key, userAgent: 'MyPlugin/1.0 WordPress/6.6');
$job = $api->createRender($manifest, 'reel-' . $postId);   // same key + same content = same job
// …later, from WP-Cron:
$job = $api->getJob($job['id']);
if ($job['status'] === 'complete') { $api->download($job['id'], $uploadsDir . '/reel.mp4'); $api->deleteJob($job['id']); }

Presets

Presets are versioned. preset=mp4 uses the current default version, and preset=mp4@1 pins version 1. A preset's output only changes through a new version announced in the changelog, so pin a version if you need output that never changes.

Example

curl -H "Authorization: Bearer $KEY" -H "Idempotency-Key: clip-1-mp4" --data-binary @clip.mov "https://this-server/v1/jobs?preset=mp4"
# {"id":"8d89…","status":"queued","preset":"mp4","preset_version":1,"warnings":[]}

curl -H "Authorization: Bearer $KEY" https://this-server/v1/jobs/8d89…
# poll every 10–30 s from a background task until status is complete or failed

curl -H "Authorization: Bearer $KEY" -o out.mp4 https://this-server/v1/jobs/8d89…/download
curl -X DELETE -H "Authorization: Bearer $KEY" https://this-server/v1/jobs/8d89…

Webhooks

Instead of polling, you can be told when a job finishes. Set an address once with PUT /v1/webhook and store the secret it returns. When a job finishes, we POST this to the address:

{"id":"0aaa…","type":"job.completed","created_at":"2026-10-30T19:24:58.612Z",
 "data":{"job":{"id":"9dc6…","status":"complete","billable_seconds":22,"download_url":"/v1/jobs/9dc6…/download", …}}}

• type is job.completed, job.failed (data.job.error says why) or ping.
• Check it's really from us. The Newsroom-Signature header is t=<unix time>,v1=<signature>, where the signature is the hex HMAC-SHA256 of <t>.<raw body> with your secret. Reject it if it doesn't match, or if t is more than 5 minutes old. The PHP client's NewsroomFfmpegClient::verifyWebhook() does both.
• Answer 200 within 10 seconds and download the video afterwards, in the background. Any other answer is retried after 1, 5, 30, 120, 360, 720 and 1440 minutes.
• The same event can arrive twice; ignore an id you've already handled. Polling still works, so keep a slow poll as a backstop.

Upload with cURL streaming from disk (CURLOPT_UPLOAD + CURLOPT_INFILE) rather than wp_remote_post(), which loads the whole file into memory. Poll from WP-Cron or Action Scheduler, never inside an editor request.

Error codes

Job error values