Recordly/docs/announcements.md

In-app announcements

Recordly can show dismissible announcements in the editor as a popup, carousel slide, lightweight live notification, or header banner. Popups can contain images or video; notifications and banners are text-only with optional buttons.

Remote announcements

Edit announcements.json on the main branch to publish an announcement without releasing a new app version. Released clients check the raw GitHub file at most once every six hours per running app instance. Fetch failures are silent and never block startup.

{
	"settings": {
		"aspectRatio": "4:3"
	},
	"announcements": [
		{
			"id": "recordly-1.4-release",
			"title": "A faster Recordly is here",
			"body": "Exports are faster and cursor motion is smoother. Thanks for using Recordly!",
			"presentation": "popup",
			"audience": "editor",
			"priority": 10,
			"mediaMode": "cover",
			"displayDurationSeconds": 15,
			"maxImpressions": 3,
			"controls": {
				"close": true,
				"dismiss": false,
				"action": true,
				"navigation": false,
				"indicators": true
			},
			"startsAt": "2026-09-01T00:00:00Z",
			"endsAt": "2026-10-01T00:00:00Z",
			"minVersion": "1.4.0",
			"media": {
				"type": "image",
				"url": "https://example.com/recordly-1.4-banner.jpg",
				"alt": "Recordly 1.4 feature preview"
			},
			"action": {
				"label": "See what changed",
				"url": "https://github.com/webadderallorg/Recordly/releases"
			}
		},
		{
			"id": "recordly-maintenance-notice",
			"title": "Quick service notice",
			"body": "Cloud sharing will undergo brief maintenance tonight.",
			"presentation": "notification",
			"audience": "editor",
			"displayDurationSeconds": 10,
			"maxImpressions": 2,
			"startsAt": "2026-09-05T00:00:00Z",
			"endsAt": "2026-09-06T00:00:00Z"
		},
		{
			"id": "recordly-editor-banner",
			"title": "Try the new editor",
			"body": "The redesigned timeline is now available.",
			"presentation": "banner",
			"audience": "editor",
			"maxImpressions": 3,
			"action": {
				"label": "Open settings",
				"section": "settings"
			}
		}
	]
}

Use a new stable id whenever an announcement should appear again. Once a user dismisses an ID, it remains dismissed. Remote items with the same ID override bundled items.

Supported fields:

• settings.aspectRatio sets one shared width:height ratio for the entire popup carousel, such as 16:9, 4:3, or 1:1. All slides keep that same size. If omitted, the bundled default is used.
• id, title, and body are required.
• presentation is popup, notification, or banner and defaults to popup. Notifications appear as text-only non-modal toasts, while banners appear only in the editor directly beneath its header. Media and mediaMode are ignored for notifications and banners. At most five notifications are shown from one feed load; banners are shown one at a time by priority.
• audience is all or editor and defaults to all.
• priority controls carousel order; larger numbers appear first.
• mediaMode is banner or cover. banner is the default current layout; cover fills the popup with the media and overlays the text.
• startsAt and endsAt are optional ISO timestamps.
• displayDurationSeconds accepts 3–300 seconds. It auto-advances popup slides; for notifications it controls how long the toast remains visible and defaults to 10 seconds.
• maxImpressions optionally limits an announcement to 1–100 app sessions. Each announcement counts at most once per session; an explicit dismissal always hides it permanently.
• controls can independently show or hide close, dismiss, action, navigation, and indicators. Every control defaults to true. Notifications and banners use only close and action; popup carousels use the other controls. Escape and clicking outside a popup remain available even when visible close controls are hidden.
• minVersion and maxVersion are optional inclusive app-version bounds.
• media.type is image or video for popups. Media URLs must be HTTPS or root-relative bundled assets. Videos can also specify posterUrl.
• action has a label and exactly one destination: an HTTPS url opened in the system browser, or an editor section opened inside the app. Supported sections are scene, cursor, webcam, captions, settings, and extensions. An action containing both destinations, neither destination, or an unknown section is ignored.

Set RECORDLY_ANNOUNCEMENTS_URL before launching the app to use a different HTTPS feed. Set it to off to disable remote announcements.

Announcements bundled with an update

Add typed entries to src/content/announcements.ts. Bundled items use the same schema and are available offline. This is useful when a message should ship atomically with a new release.

Remote content is treated as data only: HTML is not rendered, URLs are restricted, feeds are size-limited and time-limited, and malformed items are ignored.