testing library
Framework-agnostic v2 implementation conformance utilities.
Classes
- YlAirPlayPlatformPlayer
- Optional AirPlay SPI. Admission must preserve an existing playable session when unsupported; successful loads use the ordinary commit/state barrier.
- YlAirPlayRoutePickerSurface
- System route picker bound to a single native player identity.
- YlAirPlayState
- Negotiated AirPlay capability and the current session's actual route state. Enabling AirPlay never implies a device was selected or a frame presented.
- YlAndroidContentSource
- YlBufferStrategy
- Built-in strategies are optimization goals, not measured latency promises. RTMP does not support bounded; fixed transport workspace limits do not satisfy a requested buffer budget. bounded requires exact managed-media duration and byte admission limits, not a process RSS bound. Platforms unable to enforce the required budget must reject it. Durations are whole nonnegative signed32 milliseconds; bytes are positive signed32.
- YlConformanceFailure
- YlConformancePolicyCase
- One known source/policy expectation. Include at least one supported case (defaults/preferences are allowed), plus strict success and unsupported cases applicable to the adapter. Managed-route support is verified by native suites.
- YlDrmBytes
- Copies opaque DRM data. Logging this value never prints its contents.
- YlDrmConfig
- YlDrmLicenseEndpoint
- Independent binary POST policy. HTTP is allowed only for explicitly opted-in numeric loopback fixtures. Cross-origin redirects are always forbidden, because even a credential-stripped license challenge can be sensitive.
- YlDvrWindow
- Immutable DvrWindow value; validate at publication boundaries.
- YlExternalSubtitle
- One external subtitle resource and its declared request requirements. VobSub uses source for .sub and companionSource for .idx. Validate at command boundaries; only file and HTTP(S) sources are allowed.
- YlFailure
- A transportable playback failure with safe public metadata.
- YlFailureCodes
- YlFairPlayDrm
- Certificate acquisition and opaque content-ID selection belong to the host. Supply authorized bytes explicitly; no URL parsing or default ID inference.
- YlFileSource
- YlFirstFrameEvent
- YlHttpRequest
- Request metadata with explicitly scoped credentials.
- YlLimitationId
- Extensible, validated wire identifier; diagnostics never echo its value.
- YlLivePlaybackPlatformPlayer
- Optional runtime live-mode SPI; requires the operation and session mode gates. Implementations serialize mode commits with session commands and own rollback, cancellation, resource budgets and same-mode idempotence. Success occurs only after the matching committed snapshot crosses the state barrier, even when a subsequent command already changed the latest mode. A property setter or a native reply alone is not an ACK. Failed candidates preserve the prior mode, or publish session failure if safe rollback is impossible. Never reset retry budgets, relax fixed/caps/hardware/bounded policies or change playback intent.
- YlLivePlaybackState
-
An authoritative committed live mode and this session's switchable modes.
An empty list permits reporting a known Load mode without runtime switching.
Null
YlPlayerState.livePlaybackmeans no mode evidence, never a default. - YlLoadOptions
- Immutable choices for one source load.
- YlMediaDeliveryLease
- 会话必须持有租约；释放租约后接收端不能继续依赖本机媒体服务。
- YlMediaDeliveryPlatformPlayer
- 可选 SPI。每播放器最多持有一个准备操作和一个已交付租约。 新资源准备失败保留旧租约；准备成功替换并关闭旧租约。
- YlMediaDeliveryPreparation
- 同步获得取消句柄。取消已完成的准备操作不会释放其租约。
- YlMediaDeliveryProvider
- 独立媒体交付所有者；无需播放器。调用方必须释放自己创建的 provider。 每个 provider 的准入、准备和租约都与其他所有者隔离。
- YlMediaDeliveryState
- YlMediaSource
- Closed source family. Source identities and request metadata are sensitive.
- YlMediaTrack
- Immutable MediaTrack value; validate at publication boundaries.
- YlNativeVideoSurface
- An explicitly negotiated native presentation surface for one player.
- YlNetworkPolicy
- Source-specific HTTP transport guarantees. Unsupported requirements must fail. RTMP has separate native transport limits and accepts only platformDefault; managed is an HTTP policy and must be rejected by RTMP assessment. Policy durations must be whole signed32 milliseconds; timeouts are positive, retry delays are nonnegative, and counts are nonnegative signed32 integers.
- YlNetworkSource
-
HTTP(S) media or a syntactically valid RTMP(S) endpoint. Admission does not
imply native playback support: Apple supports RTMP/RTMPS; Android supports
plain RTMP. Native assessment supports automatic/FLV with automatic/live intent and rejects
HTTP request metadata, managed HTTP policy, bounded buffering, on-demand
intent, nonzero initial positions, and all runtime time seeks (including
zero) instead of ignoring them.
seekToLiveEdgesupports a fresh live open. - YlNetworkTrafficPlatformPlayer
- Optional byte observations for the newest requested network load, available before playback commit. This must never commit or replace playback state.
- YlPixelSize
- Pixel dimensions are validated at native decode and state acceptance.
- YlPlatformConformance
- Runs isolated, bounded cases without a test-framework dependency.
- YlPlatformConformanceFixture
- An implementation-owned deterministic harness. source must be supported with default load options, committing initially in buffering without Ready or First Frame until the explicit hooks below inject them. Each created player is isolated. Hook futures complete after their input is processed and its observable state/events are published, including ignored/duplicate inputs. Private transport reply ordering and controller milestone futures belong in adapter/controller suites, not this SPI-only harness.
- YlPlatformDrmLicenseTransport
- YlPlatformDrmSourceSupport
- Optional DRM configuration admission, not evidence of DRM/security support. Implement only when config v1 is consumed explicitly by assess/load and a protected session path is implemented. Per-source capability checks remain required.
- YlPlatformImplementationInfo
- Runtime implementation identity used by the controller's SPI handshake.
- YlPlatformLoadResult
- A committed session whose matching authoritative full state is already accepted by the adapter. The load barrier requires both native commit success and that state, in either arrival order, but never Ready or First Frame. Invalidated candidates fail instead of returning stale handles. Implementors bound transport waits and clean up failed loads; state remains authoritative.
- YlPlatformNativeVideoSurfaceProvider
- Optional rendering capability. Existing platform players need not implement this interface and continue to render through their Flutter texture.
- YlPlatformPlayer
- Handwritten v2 SPI. Session commands reject replaced/stopped identities; volume is player-scoped. State revisions increase across session changes. State/event streams are authoritative and dispose is idempotent.
- YlPlatformProtectedVideoSurfaceProvider
- Optional native protected view ownership; attaching does not transfer the player or authorize a frame until the matching native acknowledgment.
- YlPlaybackEngineChangedEvent
- YlPlaybackFailedEvent
- YlPlaybackMetrics
- Immutable PlaybackMetrics value; validate at publication boundaries.
- YlPlaybackSessionId
- Opaque identity for one playback session.
- YlPlayerCapabilities
- Immutable PlayerCapabilities value; validate at publication boundaries.
- YlPlayerEvent
- A discrete session event, timed from an implementation-local monotonic epoch.
- YlPlayerOptions
- Immutable player-wide choices captured at creation. The update interval must be a positive whole number of signed32 milliseconds.
- YlPlayerPlatform
- Registration point for v2 implementations. The controller verifies each created player's implementation SPI major before exposing it to callers.
- YlPlayerState
- Immutable PlayerState value; validate at publication boundaries.
- YlProtectedVideoSurface
- One committed protected presentation. None of these integers is a texture ID.
- YlRequirementId
- Extensible, validated wire identifier; diagnostics never echo its value.
- YlRetryScheduledEvent
- YlSafeDiagnostics
- Centralized sanitization for public playback diagnostics.
- YlSourceAssessment
- Immutable SourceAssessment value; validate at publication boundaries.
- YlSubtitlePlatformPlayer
- Optional subtitle SPI. Each method requires its matching capability. Success acknowledges a committed command, not first subtitle presentation. Implementations own resource cancellation and same-session command ordering.
- YlSubtitleState
- Authoritative catalog and selection. Null selection means explicitly off. Positive offset delays subtitles; negative offset advances them.
- YlSubtitleTrack
- One session-scoped stable identity; language or array index is not identity. A missing identity must not be silently remapped to a same-language track.
- YlTimeline
- Immutable Timeline value; validate at publication boundaries.
- YlVideoConstraints
- Optional positive signed32 adaptive-video limits; null is unconstrained.
- YlVideoGeometry
- Immutable VideoGeometry value; validate at publication boundaries.
- YlVideoSelection
- The authoritative video mode reported by a playback session.
- YlVideoTrackSelectionPlatformPlayer
- Optional SPI for backends that can enforce one exact video track.
- YlWidevineDrm
Enums
- YlAudioPolicy
- YlBufferStrategyKind
- YlConformancePolicyOutcome
- Expected behavior declared independently of the adapter's own assessment.
- YlDecoderEvidence
- YlDecoderMode
- YlDecoderPolicy
- YlDrmEncryption
- These enums are Dart-only; they do not alter existing native wire ordinals.
- YlDrmPostReplay
- YlFailureCategory
- YlFailureScope
- YlLivePlaybackMode
- Playback goals, not measured latency or continuity guarantees.
- YlMediaDeliveryStatus
- 生命周期与接收端播放状态无关；ready 仅代表媒体可以被拉取。
- YlMediaFormat
- YlNetworkPolicyKind
- YlPlaybackEngine
- YlPlaybackStatus
- YlPlayerOperation
- YlSourceAssessmentOutcome
- YlStreamIntent
- YlSubtitleFormat
- Format identity, not a declaration of platform decoding/rendering support.
- YlTrackKind
- YlVideoSelectionReason
Constants
- ylPlayerSpiMajor → const int
- The Dart platform contract major; independent of native transport versions.
Functions
-
validateYlDrmPlatform(
YlDrmConfig config, TargetPlatform platform, {int? androidApi}) → void -
validateYlDrmSource(
YlNetworkSource source) → void -
validateYlDvrWindow(
YlDvrWindow window) → void -
validateYlExternalSubtitles(
List< YlExternalSubtitle> subtitles) → void -
validateYlLoadOptions(
YlLoadOptions options) → void - Validates load choices before issuing a platform load command.
-
validateYlMediaTrack(
YlMediaTrack track) → void -
validateYlPixelSize(
YlPixelSize size) → void - Validate before native-to-domain decoding and before controller publication. Constructors remain const, so correctness never depends on Dart assertions.
-
validateYlPlaybackMetrics(
YlPlaybackMetrics metrics) → void -
validateYlPlaybackSessionId(
YlPlaybackSessionId sessionId) → void - Enforces playback-session identity invariants at runtime boundaries.
-
validateYlPlaybackSpeed(
double speed) → void -
validateYlPlayerCapabilities(
YlPlayerCapabilities capabilities) → void -
validateYlPlayerEvent(
YlPlayerEvent event) → void - Durations use an implementation-local monotonic epoch, never wall time. Adapters must check native time scalars before Duration construction to avoid overflowing its microsecond storage; validation cannot recover wrapped input.
-
validateYlPlayerOptions(
YlPlayerOptions options) → void - Validates creation options before a platform player is allocated.
-
validateYlPlayerState(
YlPlayerState state) → void - Validates a complete snapshot at the controller/native acceptance boundary. Ordering against previous revisions and callback sessions belongs to the controller, since a single immutable snapshot cannot establish chronology.
-
validateYlSeekPosition(
Duration position) → void - Media time uses nonnegative signed64 transport milliseconds, never the signed32 policy limit. Dart Duration stores microseconds, so all nonnegative native Dart durations already fit the transport millisecond upper bound.
-
validateYlSource(
YlMediaSource source) → void - Validates a source before any platform call. Errors never include identities or request metadata, including in ArgumentError.invalidValue.
-
validateYlSourceAssessment(
YlSourceAssessment assessment) → void -
validateYlSubtitleOffset(
Duration offset) → void - Whole milliseconds within ±7 days, checked before wire conversion.
-
validateYlSubtitleState(
YlSubtitleState state) → void -
validateYlSubtitleTrackId(
String id) → void -
validateYlTimeline(
YlTimeline timeline) → void - Raw native negative live offsets must be clamped to zero by the adapter before constructing these domain values. Other negative times are invalid.
-
validateYlTrackId(
String trackId) → void -
validateYlVideoConstraints(
YlVideoConstraints constraints) → void - Used for both initial load and runtime adaptive-video constraint commands.
-
validateYlVideoGeometry(
YlVideoGeometry geometry) → void -
validateYlVolume(
double volume) → void -
ylDrmException(
String code) → YlPlayerException - Constructs diagnostics from allowlisted code only; never takes server prose.
Typedefs
-
YlDrmLicenseExchange
= Future<
YlDrmBytes> Function(YlDrmLicenseEndpoint endpoint, YlDrmBytes challenge, Future<void> cancelled) - Configured by the controller. Cancellation settles on completion as well, so a transport must remove listeners when its request finishes.
Exceptions / Errors
- YlPlayerException
- Exception wrapper for a transportable playback failure.