Skip to content

[YouTube] Expose captionTracks name on SubtitlesStream - #1551

Merged
TobiGr merged 1 commit into
TeamNewPipe:devfrom
ibrahim-iqbal:fix/9218-subtitle-name
Oct 5, 2026
Merged

TobiGr merged 1 commit into
TeamNewPipe:devfrom
ibrahim-iqbal:fix/9218-subtitle-name

Conversation

@ibrahim-iqbal

Copy link
Copy Markdown
Contributor

What

Pass the service-provided name field on each YouTube caption track through
SubtitlesStream, so downstream clients can tell apart tracks that share a
language code.

Addresses TeamNewPipe/NewPipe#9218 (reporter observed two tracks both
labelled "English" on a video that actually has distinct CC1 and DTVCC1
tracks).

Why

For the issue's test video (BISyIBU2gVY), YouTube's captionTracks
response contains two entries, both with languageCode: "en" but distinct
name fields:

{ "languageCode": "en", "name": "English - CC1",    "vssId": ".en.uYU-mmqFLq8" }
{ "languageCode": "en", "name": "English - DTVCC1", "vssId": ".en.JkeT_87f4cc" }

Today the extractor only forwards languageCode, so NewPipe calls
SubtitlesStream#getDisplayLanguageName() → locale.getDisplayName(locale)
and gets the same "English" string for both. YouTube's own UI uses the
name field, which is why the web client shows them correctly.

How

  • SubtitlesStream: new optional nullable name field with a Builder#setName(String)
    setter and a getName() getter. Backwards compatible — existing extractors that
    don't call setName keep returning null here, so their behaviour is unchanged.
  • YoutubeStreamExtractor#getSubtitles: read the name object off each
    captionTrack via the existing getTextFromObject helper (which already handles
    both the simpleText and runs shapes and returns null when the field is
    missing), and forward it to the builder.

The downstream consumer in NewPipe should prefer getName() when non-null
and fall back to getDisplayLanguageName() otherwise.

Tests

Added SubtitlesStreamBuilderTest with three focused checks:

  • the name round-trips Builder → getName()
  • an explicit null is accepted
  • a Builder that never calls setName yields getName() == null
    (guarantees backwards compatibility for every other service)

All existing extractor tests still pass locally against the fork.

Follow-up

NewPipe PR against TeamNewPipe/NewPipe to actually consume getName() in
PlayerHelper#captionLanguageOf is coming right after this.

Checklist

  • I carefully read the contribution guidelines and agree to them.
  • I have tested the API against NewPipe — the change is purely additive on the API surface (new nullable field + new getter), existing callers are unaffected.
  • I agree to create a pull request for NewPipe as soon as possible to make it compatible with the changed API.

AI assistance

Used Claude to help scope the fix (locating captionTracks handling in both repos, scanning the test video's player response to confirm the name field exists per track, and sketching the test file). The code changes and the test content were reviewed and edited line-by-line against the surrounding codebase conventions before pushing.

YouTube sometimes ships multiple caption tracks that share a language
code (e.g. two "en" tracks with different `name` fields like
"English - CC1" and "English - DTVCC1"). The extractor currently only
passes the language code through, so downstream pickers can't tell
them apart and render them as duplicate "English" entries.

Pass the service-provided name through SubtitlesStream so clients can
show the full descriptive label when available, falling back to the
locale-derived display name when it isn't.

Addresses TeamNewPipe/NewPipe#9218.
@sonarqubecloud

sonarqubecloud Bot commented Oct 4, 2026

Copy link
Copy Markdown

@TobiGr TobiGr added enhancement New feature or request YouTube Service, https://www.youtube.com/ labels Oct 4, 2026

@TobiGr TobiGr left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thank you

@TobiGr
TobiGr merged commit 65cabc2 into TeamNewPipe:dev Oct 5, 2026
2 of 3 checks passed
TobiGr pushed a commit to TeamNewPipe/NewPipe that referenced this pull request Oct 6, 2026
YouTube ships a user-facing `name` field per caption track that can
differ even when the language code is identical (e.g. "English - CC1"
vs "English - DTVCC1"). The extractor now surfaces that string via
`SubtitlesStream#getName()`; prefer it in the player's caption menu so
tracks that share a language code can finally be told apart.

Falls back to the locale-derived display name when the service doesn't
expose a track name.

Fixes #9218.

Depends on TeamNewPipe/NewPipeExtractor#1551 — the version-catalog
pointer in libs.versions.toml is temporarily targeted at
ibrahim-iqbal/NewPipeExtractor and will be flipped back to
TeamNewPipe once the extractor PR merges.
@ibrahim-iqbal
ibrahim-iqbal deleted the fix/9218-subtitle-name branch November 6, 2026 13:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request YouTube Service, https://www.youtube.com/

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants