Skip to content

Let videos take alt text on Mastodon, Bluesky, Threads and Discord - #511

Merged
paulocastellano merged 5 commits into
mainfrom
feat/video-alt-text-mastodon-bluesky
Nov 17, 2026
Merged

paulocastellano merged 5 commits into
mainfrom
feat/video-alt-text-mastodon-bluesky

Conversation

@paulocastellano

@paulocastellano paulocastellano commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Mastodon, Bluesky, Threads and Discord all document alt text on a video, but TryPost only sent it for images, and the media editor only offered the Alt tab on images. With this PR, every network that takes alt text on a video gets it, so images and videos are on par.

Closes #507. Split out of #310.

What each API documents

Network Field Source
Bluesky alt on app.bsky.embed.video: "Alt text description of the video, for accessibility." lexicons/app/bsky/embed/video.json
Mastodon description on POST /api/v2/media: "A plain-text description of the media, for accessibility purposes." Not limited to images; the server validates it on every media type (app/models/media_attachment.rb). media methods
Threads alt_text: "The accessibility text label or description for an image or video in a Threads post", up to 1,000 characters. publishing reference
Discord Attachment description: "description (alt text) for the file (max 1024 characters)". message resource

The other networks take no alt text on a video (X and Instagram: images only; Facebook, TikTok, YouTube, Telegram and Google Business: no field). LinkedIn and Pinterest don't document it either way, so they are left out.

Changes

  • Rule: Platform::supportsVideoAltText() (Bluesky, Mastodon, Threads, Discord) and ContentType::supportsVideoAltText(), shared as supports_video_alt_text in the media rules (composer props, GET /api/content-types, list-content-types-tool). The image side is renamed to match (supportsAltText() → supportsImageAltText() on both enums and in the TypeScript rules); the public supports_alt_text key stays as it is, so API and MCP clients see no change.
  • Editor tabs: editorTabsFor() reads the optional tabs of a video and of an image from one list each (VIDEO_TABS, IMAGE_TABS).
  • Publishers:
    • Mastodon sends the description on a video upload.
    • Bluesky adds alt to the video embed (omitted when empty).
    • Threads sends alt_text on a single video container and on video carousel children.
    • Discord sets the attachment description on a video.
    • The text is cut to each network's limit through altTextFor(), as for images.
  • Editor: a video on those networks shows the ALT button on its tile, and the editor opens on the Alt tab with the video on the stage. "Generate with AI" is hidden for a video, since the server only writes alt text for images.
  • API and MCP: the alt shorthand on a media item now keeps the alt on a video too (still ignored for a PDF). The tool descriptions say when it is sent.

Tests

  • Publishers (Mastodon, Bluesky, Threads single video and carousel, Discord): the alt reaches the video. The old tests that asserted the opposite now assert this, and Bluesky still sends no alt without one.
  • ContentTypeTest: only those four types take video alt; the listing carries the flag.
  • MediaEditorPresetsParityTest: the TypeScript editor offers Alt on a video exactly where the backend takes it.
  • InlineMediaShapeTest / AttachMediaFromUploadToolTest: the alt shorthand is kept on a video and ignored on a PDF.
  • Browser (MediaEditorTest, one case per network): open the ALT button on a video, check no AI button, type the alt, save, and check it is stored.
  • No side effects on the other networks: X, LinkedIn and Instagram carousels (existing tests), and now Instagram reels and Facebook videos and reels, still send no alt with a video. Every platform with video alt also takes image alt, which altTextFor() relies on for the limit.
  • Editing a video's alt keeps its stored cover frame (cover_offset_ms).
  • Each new test was checked to fail without its change.
  • Full suite (11,320 tests), MediaEditorTest.php (51 browser tests), Pint, ESLint and vue-tsc pass.

Manual test plan

Run against real accounts on November 17, 2026. Threads, X, LinkedIn, Facebook and Pinterest are not connected in the test workspace, so their items stay open.

Video alt text, the new behaviour

  • Mastodon
    • A video with alt: the description is on the video (media_attachments[].description on the status).
    • A video without alt: published with no description and no error.
    • An alt over the limit (1,602 characters): cut to 1,500.
  • Bluesky
    • A video with alt: the alt is on the app.bsky.embed.video record.
    • A video without alt: published with no alt key and no error.
    • A long alt (1,602 characters) goes out whole. The app caps any alt at 2,000 characters, which is Bluesky's limit too, so Bluesky never needs to cut it.
  • Threads (not connected)
    • Publish a single video with alt. The alt is on the video.
    • Publish a carousel with two videos, each with its own alt. Each video keeps its own text.
    • Publish a carousel that mixes an image and a video, both with alt. Both keep their text.
    • Publish a video without alt. It goes out with no error.
  • Discord (#off-topic)
    • A video with alt: the attachment description holds it.
    • A video without alt: published with no description and no error.
    • An alt over the limit (1,602 characters): cut to 1,024.

Media editor

  • A video on Mastodon, Bluesky or Discord shows the ALT button on its tile; clicking it opens the editor on the Alt tab with the video on the stage.
  • On a video, the Alt tab has no "Generate with AI" button.
  • Write alt on a video, save the draft, reopen it. The alt is still there.
  • Clear a video's alt and save. It is removed (alt_text gone from the media meta).
  • Set a cover frame on a video (Instagram reel in the same post), then edit only its alt. The cover frame stays (0:10.2 before and after, and the published reel uses that frame).
  • A video on a network without video alt shows no ALT button: TikTok and YouTube show only the cover pencil and the editor has only the Thumbnail tab; the Instagram card alone shows only the pencil.
  • A post for Bluesky and Instagram with one video: the tile shows ALT (for Bluesky) and the pencil (for the Instagram cover); Bluesky gets the alt and the Instagram reel is published with no alt_text.
  • A GIF has no editor buttons.

Things that could break (image alt and other networks)

  • Image alt still works on each network that took it before:
    • Instagram carousel (alt_text on each child), Bluesky, Mastodon and Discord: four images, each with its own alt, all four kept in order.
    • X, LinkedIn, Facebook, Pinterest and Threads (not connected).
  • "Generate with AI" still shows on an image and writes the alt.
  • The image editor still opens on Edit first, with the network's crop presets, then Description and Tags (Instagram).
  • Instagram people tags on an image still save and publish.
  • Instagram reel with a video: published as REELS, no alt sent, no error.
  • Facebook video / reel (not connected).
  • YouTube and TikTok video: publish as before (their code is untouched).
  • Bluesky post with four images, each with its own alt: all four keep their alt.
  • Bluesky post with images and a video: the composer refuses the mix ("You can't combine images and video in the same post"), as before.
  • Threads text-only post, single image post and image carousel (the single media code was merged), ghost post and topic tag (not connected).
  • Discord PDF: publishes as before.
  • LinkedIn document (PDF) (not connected).

API and MCP

Covered by the automated tests (InlineMediaShapeTest, AttachMediaFromUploadToolTest, ContentTypeTest, PlatformToolTest); not run by hand.

  • POST /api/posts with a video item carrying alt for Mastodon: the post stores the alt on the video and publishes it.
  • The same with a PDF carrying alt: the alt is ignored and the post is created.
  • GET /api/content-types: each type carries supports_video_alt_text (true only on bluesky_post, mastodon_post, threads_post and discord_message) and still carries supports_alt_text unchanged.
  • MCP list-content-types-tool shows the same flag.
  • MCP attach-media-from-url-tool and attach-media-from-upload-tool with a video and alt: the alt is stored on the video.

Paulo Castellano added 5 commits November 17, 2026 12:08
The four networks document alt text on a video, but TryPost only sent it
for images and the media editor only offered the Alt tab on images.

- Platform::supportsVideoAltText() / ContentType::supportsVideoAltText(),
  shared as supports_video_alt_text in the media rules (composer, API, MCP).
- Mastodon sends the media description, Bluesky the video embed alt,
  Threads alt_text on video containers (single and carousel), Discord the
  attachment description.
- The media editor offers the Alt tab on those videos; AI alt generation
  stays image only.
- The API and MCP alt shorthand now keeps alt on a video (still ignored
  for a PDF).

Closes #507
… and guard the other networks

- Platform::supportsAltText() and ContentType::supportsAltText() become
  supportsImageAltText(), next to supportsVideoAltText(); the public
  supports_alt_text key is unchanged for API and MCP clients.
- editorTabsFor() reads the optional tabs of a video or an image from one
  list each instead of nested spreads.
- Tests: every platform with video alt also takes image alt; Facebook
  videos and reels and Instagram reels still send no alt; editing a video's
  alt keeps its cover frame.
- Threads: one publishSingleMedia() for an image or a video, and
  mediaParams() building the type, URL and alt text for single posts and
  carousel children alike.
- Bluesky: mediaEmbed() picks images or a video; imagesEmbed() and
  videoEmbed() build each, sharing one upload failure.
@paulocastellano
paulocastellano merged commit ada819b into main Nov 17, 2026
24 of 28 checks passed
@paulocastellano
paulocastellano deleted the feat/video-alt-text-mastodon-bluesky branch November 17, 2026 21:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Alt text on videos for Mastodon and Bluesky

1 participant