New parameters to "config" property to override streams media flags

[CastagnaIT]

Description

New parameters to inputstream.adaptive.config:

• media_audio_langcode_default: Set the "default" flag to the audio streams with specified language code
• media_audio_langcode_original: Set the "original" flag to the audio streams with specified language code
• media_audio_stereo_pref: Can be set to true when you want prefer stereo track as default instead of multi-channels (it will be applied to media_audio_langcode_default and media_audio_langcode_original)
• media_audio_type_pref: Can be set to original to prefer set as default the stream with original language, or impaired to prefer set as default the stream for impaired, otherwise left empty value for default behaviour.
• media_subtitle_langcode_default: Set the "default" flag to the subtitle streams with specified language code

about the language code format used should be the IETF RFC 5646 (BCP-47), but i suggest you to check also your manifest data

The property inputstream.adaptive.original_audio_language is now deprecated and will be removed from next kodi (major) version

NOTE FOR LANG CODE VARIANTS: At moment Kodi dont support any kind of track auto-selection fallback for language code that have variants e.g. "pt-BR" for Brazilian Portuguese vs "pt" for Portuguese, so here at moment its the same, if you set as default "pt-BR" but exists only a "pt" stream no stream will be set as default. This could be improved in future but for now we keep it simple.

Motivation and context

Completed fix for #422 in more generic way

this will allow to override streams media flags in a generic way without being strictly limited to a single manifest type

the reason behind this is that Kodi stream media flags have not always have the same meaning of manifests attributes
and/or there are video services that dont follow exactly the specs and lead to wrong flags set to the audio/subtitle tracks

this will make the life easier for devs without the needs to implement a proxy on each addon to modify on the fly the manifest media flags

HLS manifest side effect

The HLS manifests dont always provide the appropriate language codes and also dont always provide the right number of audio channels in the manifest, therefore the use of these new overrides may fails, you will need to check what your provider offers and act accordingly

How has this been tested?

Screenshots (if appropriate):

Types of change

• Bug fix (non-breaking change which fixes an issue)
• Clean up (non-breaking change which removes non-working, unmaintained functionality)
• Improvement (non-breaking change which improves existing functionality)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that will cause existing functionality to change)
• Cosmetic change (non-breaking change that doesn't touch code)
• None of the above (please explain below)

Checklist:

• I have read the Contributing document
• My code follows the Code Guidelines of this project
• My change requires a change to the Wiki documentation
• I have updated the documentation accordingly

[kodiai]

Decision: APPROVE

Issues: none

Evidence:

• Review prompt covered 10 changed files.
• Review scope note: output was scoped by prompt budget limits; Review Details include bounded counts only.

Review Details

• Review plan: ready hash=a5cede901dd3 route=standard task=review.full files=10 lines=286(local-diff) budget=na/788s gates=3/3 publish=canonical-visible-surface graph=skipped candidates=preferred doctrine=disabled/0/0/0 reasons=disabled

• Review reducer: ready input=4 kept=4 suppressed=0 rewritten=0 deprioritized=0 lowConfidence=0 auditEvents=0 severityDemoted=0 graphValidated=0 graphUncertain=0 doctrine=disabled/0/0/0 reasons=disabled

• Review candidates: shadow recorded=4 rejected=0 errors=0 artifact=present repo=xbmc-inputstream.adaptive pr=2040 key=kodiai-review-output:v1:inst-109141824:xbmc-inputstream.adaptive:pr-2040:action- delivery=586e0e10-5dd9-11f1-88cf-e9d70bb219ba

• Review candidate publication: mode=blocked approved=4 rewritten=0 publishable=0 nonPublishable=4 fixBlocked=4 published=0 directFallback=0 reasons=fix-eligibility-blocked movedToDetails=0 detailsOmitted=0 buckets=blocked:4:fix-eligibility-blocked+missing-replacement

• Files reviewed: 10

• Findings: 0 critical, 0 major, 0 medium, 0 minor

• Lines changed: +264 -22

• Profile: balanced (auto, lines changed: 286)

• Contributor experience: profile-backed (using linked contributor profile guidance)

• Shadow specialist: lane=docs-config-truth status=skipped reason=no-operator-truth-paths candidateCount=0 decisionCount=0 decisionCounts=candidate:0,duplicate:0,disagreement:0,dismissed:0,unclassifiable:0 duplicateCount=0 disagreementCount=0 dismissedCount=0 unclassifiableCount=0 truncatedCandidateCount=0 metricAvailability=token:n,cost:n,latency:n visiblePublicationDenied=true approvalPublicationDenied=true privateOnly=true shadowOnly=true redacted=raw:n,publication:n,approval:n,unsafe:0 correlationKey=25eaac2297f0cff1 deliveryId=586e0e10-5dd9-11f1-88cf-e9d70bb… reviewOutputKey=kodiai-review-output:v1:inst-10…

• M072 candidate publication bridge: status=denied; bridgeVersion=candidate-publication-bridge.v1; bridgeId=candidate-publication-record:5a5dbfee65d9ea343595167a3d459a07; recordKey=candidate-publication-record:5a5dbfee65d9ea343595167a3d459a07; correlationKey=candidate-publication-bridge:7c66eed7cd523b392c516178e86eb0c3; source=review-handler-publication; candidateRef=candidate-publication-summary-c98875b3; verification=none; counts=candidateCount:0,evidenceCount:0,verifiedCount:0,partiallyVerifiedCount:0,unverifiedCount:0,disprovenCount:0,publicationEligibleCount:0,malformedRecordCount:0,unsafeInputFieldCount:0; reasons=no-evidence,publication-ineligible; malformed=none; presence=deliveryId:y,reviewOutputKey:y,upstreamCorrelationKey:y,policyCorrelationKey:y; handoffOwner=available; redaction=privateOnly:y,rawPayloads:n,publicationFields:n,evidencePayloads:n,githubCommentBody:n,reducerRawPayload:n,discardedRawPayload:n,discardedPublicationFields:n,discardedEvidencePayloads:n

• Review finding lifecycle: status=normalized; counts=input:4,recorded:4,rejected:0,unsafeInputFields:0; correlation=repo:y,pull:y,reviewOutputKey:y,deliveryId:y,commit:y; statuses=detected:4,open:4,suggested:0,validated:0,revalidated:0,resolved:0,blocked:0,degraded:0; severity=critical:1,major:2,medium:1,minor:0; actionability=actionable:0,needs-human-review:4,needs-reproduction:0,blocked:0,not-actionable:0; reasons=automatic-detected,automatic-open,automatic-review; rejected=none; redaction=privateOnly:y,rawPrompts:n,rawModelOutput:n,candidateBodies:n,toolPayloads:n,secretLike:n,diffs:n,unboundedArrays:n,unsafeFields:0

• Review validation truth: status=normalized; counts=detected:4,suggested:0,validated:0,revalidated:0,resolved:0,blocked:0,degraded:0,open:4,uncertain:0,inputFindings:4,unsafeInputFields:0; evidence=fresh:0,stale:0,missingValidation:4,missingRevalidation:4; reasons=validation-missing:4; refs=rfl-5f79995c0453dcd0:open:validation-missing:fix:n:validation:n:revalidation:n,rfl-3a49f450b4249b98:open:validation-missing:fix:n:validation:n:revalidation:n,rfl-e280727943b713ad:open:validation-missing:fix:n:validation:n:revalidation:n,rfl-1fabf24b95acbeb3:open:validation-missing:fix:n:validation:n:revalidation:n; correlation=reviewOutputKey:y,deliveryId:y; redaction=privateOnly:y,rawPrompts:n,rawModelOutput:n,candidateBodies:n,replacementText:n,toolPayloads:n,secretLike:n,diffs:n,unboundedArrays:n,unsafeFields:0

• Review completed: 2026-06-01T16:55:03.921Z

• Total wall-clock: 9m 8s

• Phase timings:

  • queue wait: 0ms
  • workspace preparation: 1.3s
  • retrieval/context assembly: 3.4s
  • executor handoff: 52s
  • remote runtime: 8m 5s
  • publication: 3.3s

• Tokens: 964 in / 20,953 out | 0.7265

• Keyword parsing: No keywords detected

• Budget behavior: scoped (prompt-budget-limited).

• Prompt budget: 5 sections, 2 trimmed, 0 bypassed, 2689 trimmed tokens.

• Cache behavior: 2 observations, 1 hits, 1 misses, 0 degraded, 0 bypassed.

• Continuation behavior: 0 observations, 0 compacted, 0 fallback, 0 degraded, 0 bypassed.

[CastagnaIT]

@kodiai please review

[kodiai]

📝 Kodiai Draft Review Summary

What Changed

Adds new configuration parameters to inputstream.adaptive.config that allow overriding stream media flags (default, original) for audio and subtitle tracks, providing a generic way to handle manifests that don't follow specs correctly. Reviewed: core logic

Strengths

• ✅ Comprehensive fallback logic in FixStreamsFlags() provides multiple strategies to find matching audio streams, improving robustness when exact matches aren't available (src/common/AdaptiveTree.cpp:184-250)
• ✅ Proper iterator validation throughout FixStreamsFlags() prevents dereferencing invalid iterators before accessing stream objects (src/common/AdaptiveTree.cpp:253)

Observations

Impact

[MAJOR] src/common/AdaptationSet.cpp (262): Array out-of-bounds access when representations vector is empty
Missing bounds check before accessing GetRepresentations()[0] causes undefined behavior when adaptation sets have no representations. This is triggered by the new audio flag override logic when calling FindAudioAdpSet().

Verdict

🔴 Address before merging -- 1 blocking issue(s) found (MAJOR)

[CastagnaIT]

@kodiai updated please review

[kodiai]

kodiai response

I don't have access to the PR diff or changes through the available tools. Could you point me to the specific files that were updated in this revision?

[CastagnaIT]

@kodiai updated please review

[kodiai]

Decision: APPROVE

kodiai response

Decision: APPROVE
Issues: none

Evidence:

• Bounds checking properly implemented: AdaptationSet.cpp:261,282 now verify !GetRepresentations().empty() before accessing [0]
• Iterator validation correct throughout AdaptiveTree.cpp:167-273: all accesses check != adpSets.cend() before dereferencing
• Previous array out-of-bounds issue resolved

[CastagnaIT]

@matthuisman if iirc you was using inputstream.adaptive.original_audio_language on some add-on,
have you some time to test this new way?