Structure

SessionDiagnosticReport

struct SessionDiagnosticReport

Declared in Sources/PrismCore/Diagnostics/SessionDiagnosticReport.swift · PrismCore 3.5.4

Everything the engine knows about one playback, as one value a host can attach to a bug report: which build, what the source turned out to be, where it was routed and why, where startup spent its time, and what the running session ran into.

It exists because all of that was already known, but in a dozen places and in no serializable shape, so every field report started with the same round of questions (which build, which container, planned or sequential, how many repairs) the engine could have answered itself.

Take one with PrismCoreSession.diagnosticReport(), or, for a source that never got a session (declined, or routed to the software path), with PrismCoreEngine.diagnosticReport(for:decision:). jsonData() is the shape to paste.

The JSON is a contract. schemaVersion names it; fields are only ever added, never renamed or repurposed, so a reader written against version 1 keeps reading every later report.

Nothing secret leaves in it — see Redaction for what is withheld: HTTP headers, the URL's query, fragment and credentials, and every path on this device's disk. Only values the engine actually holds are reported; anything it did not measure is absent rather than guessed.

Initializers

init(jsonData:)source

init(jsonData: Data) throws

Reads what jsonData() wrote.

Instance properties

schemaVersion source

var schemaVersion: Int

No documentation comment in the source.

engine source

var engine: Engine

No documentation comment in the source.

source source

var source: Source

No documentation comment in the source.

decision source

var decision: Decision?

The routing verdict. nil only when the source was never described (a session reporting before its remux opened anything).

options source

var options: Options?

What the session was built with. nil for a report taken from a probe alone, where no session existed to have options.

startup source

var startup: Startup

No documentation comment in the source.

runtime source

var runtime: Runtime?

The running session. nil for a report taken from a probe alone.

Instance methods

jsonData()source

func jsonData() throws -> Data

Pretty-printed with sorted keys, so two reports diff line by line and the same report always prints the same bytes.

Never throws for want of a finite number: a non-finite double (a frame rate libavformat could not work out, say) is written as the string "nan"/"inf"/"-inf", because a "copy diagnostics" button that fails on the very source it is meant to describe is no button.

Type properties

currentSchemaVersion source

static let currentSchemaVersion: Int

The schema this build writes. Bumped only for an additive change a reader might want to detect; never for a breaking one, which this schema does not make.

Structure

SessionDiagnosticReport.Decision

struct Decision

No documentation comment in the source.

Instance properties

engine source

var engine: String?

remux or software; nil when the router declined outright (no video, no decoder), in which case reason says why.

reason source

var reason: String

No documentation comment in the source.

Structure

SessionDiagnosticReport.Engine

struct Engine

Which build answered. FFmpegBuild.configuration is deliberately not here: the configure line carries the build machine's paths.

Instance properties

prismCoreVersion source

var prismCoreVersion: String

No documentation comment in the source.

ffmpegVersion source

var ffmpegVersion: String

FFmpeg's own build identity (FFmpegBuild.versionInfo).

libraries source

var libraries: [Library]

No documentation comment in the source.

mismatchedLibraries source

var mismatchedLibraries: [String]

Names of the libraries whose major version disagrees with the headers this build saw. Empty on a sane install.

capabilities source

var capabilities: Capabilities

No documentation comment in the source.

platform source

var platform: String

iOS, tvOS, visionOS or macOS.

osVersion source

var osVersion: String

No documentation comment in the source.

Structure

SessionDiagnosticReport.Engine.Capabilities

struct Capabilities

FFmpegBuild.Capabilities, field for field.

Instance properties

hasEAC3Encoder source

var hasEAC3Encoder: Bool

No documentation comment in the source.

audioBridgeEncoder source

var audioBridgeEncoder: String?

No documentation comment in the source.

av1Decoder source

var av1Decoder: String?

No documentation comment in the source.

isAV1HardwareSupported source

var isAV1HardwareSupported: Bool

No documentation comment in the source.

hasDialogueBoost source

var hasDialogueBoost: Bool

No documentation comment in the source.

gpuDeinterlacer source

var gpuDeinterlacer: String?

No documentation comment in the source.

Structure

SessionDiagnosticReport.Engine.Library

struct Library

No documentation comment in the source.

Instance properties

name source

var name: String

No documentation comment in the source.

compiled source

var compiled: String

No documentation comment in the source.

loaded source

var loaded: String

No documentation comment in the source.

isABIMatched source

var isABIMatched: Bool

No documentation comment in the source.

Structure

SessionDiagnosticReport.Failure

struct Failure

A failure, classified the way a host branches on it (PrismCoreError).

Instance properties

kind source

var kind: String

The PrismCoreError case name.

retryability source

var retryability: String

No documentation comment in the source.

description source

var description: String

The error's description, with every secret the report knows of cut out of it (see Redaction).

Structure

SessionDiagnosticReport.Options

struct Options

PrismCoreSession.Options without anything that names a place: keyframeIndexCacheDirectory is reduced to whether it is set, the headers to the count in Source, external subtitles to a count.

Instance properties

display source

var display: Display

No documentation comment in the source.

segmentCacheBytes source

var segmentCacheBytes: Int?

No documentation comment in the source.

forceMuxedShape source

var forceMuxedShape: Bool

No documentation comment in the source.

keyframeIndexCacheEnabled source

var keyframeIndexCacheEnabled: Bool

No documentation comment in the source.

dialogueBoost source

var dialogueBoost: [String]

No documentation comment in the source.

preferredAudioLanguage source

var preferredAudioLanguage: String?

No documentation comment in the source.

preferredSubtitleLanguage source

var preferredSubtitleLanguage: String?

No documentation comment in the source.

audioDelaySeconds source

var audioDelaySeconds: Double

No documentation comment in the source.

coordinatedHTTP source

var coordinatedHTTP: Bool

No documentation comment in the source.

reachability source

var reachability: String

loopbackOnly or localNetworkUnencryptedForAirPlay.

externalSubtitleCount source

var externalSubtitleCount: Int

No documentation comment in the source.

Structure

SessionDiagnosticReport.Options.Display

struct Display

No documentation comment in the source.

Instance properties

isHDRReady source

var isHDRReady: Bool

No documentation comment in the source.

isDolbyVisionCapable source

var isDolbyVisionCapable: Bool

No documentation comment in the source.

panelIsCurrentlyHDR source

var panelIsCurrentlyHDR: Bool?

No documentation comment in the source.

source source

var source: String

No documentation comment in the source.

Structure

SessionDiagnosticReport.Runtime

struct Runtime

No documentation comment in the source.

Instance properties

started source

var started: Bool

No documentation comment in the source.

stopped source

var stopped: Bool

No documentation comment in the source.

uptimeSeconds source

var uptimeSeconds: Double?

Since start() was called; nil before.

sourceBytesRead source

var sourceBytesRead: Int64

No documentation comment in the source.

playbackEvents source

var playbackEvents: [Event]

The newest PlaybackEvents, oldest first, kept whether or not a host registered for them.

playbackEventsDropped source

var playbackEventsDropped: Int

Older events the bounded window let go.

timestampRepairs source

var timestampRepairs: TimestampRepairs?

No documentation comment in the source.

audioRenditionProductions source

var audioRenditionProductions: [AudioRendition]

No documentation comment in the source.

audioRenditionSummary source

var audioRenditionSummary: String?

AudioRenditionProduction.summary, the line a host logs. nil before the master is written and in the muxed shape.

objectAudio source

var objectAudio: [ObjectAudio]

No documentation comment in the source.

dolbyVisionConversion source

var dolbyVisionConversion: DolbyVisionConversion?

No documentation comment in the source.

retention source

var retention: Retention

No documentation comment in the source.

remuxFailure source

var remuxFailure: Failure?

The remux's terminal error, classified, once it died.

audioDelaySeconds source

var audioDelaySeconds: Double

No documentation comment in the source.

pendingAudioDelaySeconds source

var pendingAudioDelaySeconds: Double?

No documentation comment in the source.

subtitleDelaySeconds source

var subtitleDelaySeconds: Double

No documentation comment in the source.

Structure

SessionDiagnosticReport.Runtime.AudioRendition

struct AudioRendition

No documentation comment in the source.

Instance properties

streamIndex source

var streamIndex: Int

No documentation comment in the source.

dialogueBoost source

var dialogueBoost: String?

No documentation comment in the source.

encodes source

var encodes: Bool

No documentation comment in the source.

production source

var production: String

eager, lazy or omitted.

Structure

SessionDiagnosticReport.Runtime.DolbyVisionConversion

struct DolbyVisionConversion

No documentation comment in the source.

Instance properties

convertedRPUs source

var convertedRPUs: Int

No documentation comment in the source.

failedRPUs source

var failedRPUs: Int

No documentation comment in the source.

droppedEnhancementLayerNALs source

var droppedEnhancementLayerNALs: Int

No documentation comment in the source.

staleUnconvertedPackets source

var staleUnconvertedPackets: Int

No documentation comment in the source.

isClean source

var isClean: Bool

No documentation comment in the source.

Structure

SessionDiagnosticReport.Runtime.Event

struct Event

No documentation comment in the source.

Instance properties

kind source

var kind: String

The PlaybackEvent case name.

atSeconds source

var atSeconds: Double?

Since start(), negative for an event from before it; nil while the session has not been started.

path source

var path: String?

The loopback path served (never a source path).

waitedSeconds source

var waitedSeconds: Double?

No documentation comment in the source.

stalledSeconds source

var stalledSeconds: Double?

No documentation comment in the source.

lastPTS source

var lastPTS: Double?

No documentation comment in the source.

retryAfterSeconds source

var retryAfterSeconds: Double?

No documentation comment in the source.

segments source

var segments: Int?

The segment count of a plan a late index load stored.

attempt source

var attempt: Int?

A producer recovery's re-open count inside its 60 s window.

failure source

var failure: Failure?

The failure a producer recovered from, or the one it died of.

Structure

SessionDiagnosticReport.Runtime.ObjectAudio

struct ObjectAudio

No documentation comment in the source.

Instance properties

streamIndex source

var streamIndex: Int

No documentation comment in the source.

complexityIndex source

var complexityIndex: Int?

No documentation comment in the source.

claimedByMetadata source

var claimedByMetadata: Bool

No documentation comment in the source.

isObjectAudio source

var isObjectAudio: Bool

No documentation comment in the source.

wasMissedByMetadata source

var wasMissedByMetadata: Bool

No documentation comment in the source.

Structure

SessionDiagnosticReport.Runtime.Retention

struct Retention

No documentation comment in the source.

Instance properties

budgetBytes source

var budgetBytes: Int?

segmentCacheBytes; nil keeps everything.

evictedSegments source

var evictedSegments: Int

Segments evicted to stay inside it, over the whole session.

Structure

SessionDiagnosticReport.Runtime.TimestampRepairs

struct TimestampRepairs

No documentation comment in the source.

Instance properties

missingDTSFilled source

var missingDTSFilled: Int

No documentation comment in the source.

nonMonotonicDTSBumped source

var nonMonotonicDTSBumped: Int

No documentation comment in the source.

ptsRaisedToDTS source

var ptsRaisedToDTS: Int

No documentation comment in the source.

total source

var total: Int

No documentation comment in the source.

Structure

SessionDiagnosticReport.Source

struct Source

No documentation comment in the source.

Instance properties

url source

var url: String?

The remote URL without credentials, query or fragment — the places servers put tokens. nil for a local file, and for a URL that could not be taken apart (withheld rather than risked).

fileName source

var fileName: String?

A local file's name, without its directory. The directory is this device's layout (a user name, a mount point) and says nothing about the media; the name is what a reporter recognises.

scheme source

var scheme: String?

No documentation comment in the source.

httpHeaderCount source

var httpHeaderCount: Int

How many request headers the host supplied. Their names and values are never exported.

hostInput source

var hostInput: Bool

Whether the host supplied the bytes itself (PrismCoreInput).

byteSize source

var byteSize: Int64?

The transport's length for the source, when the probe measured it.

durationSeconds source

var durationSeconds: Double?

No documentation comment in the source.

info source

var info: SourceDescription?

No documentation comment in the source.

structure source

var structure: SourceStructure?

The container layout, without the keyframe timestamps (an index load can export twenty thousand of them; the report keeps the count and the completeness).

Structure

SessionDiagnosticReport.Startup

struct Startup

No documentation comment in the source.

Instance properties

checkpoints source

var checkpoints: [Checkpoint]

The stages start() reached, in order — recorded whether or not the host registered for startupCheckpoints(). A startup that failed ends wherever it got to, which is the point.

planOrigin source

var planOrigin: String?

keyframeIndexCache, builtFromSource or sequential.

planSegments source

var planSegments: Int?

Planned segment count; 0 for a sequential session.

plan source

var plan: Plan?

The plan start() built, used or not (a uniform plan runs sequential). nil without one (no duration, no demand mode).

probeTiming source

var probeTiming: ProbeTiming?

The routing probe's phases, for a session built from a ProbedSource (or a report taken from one).

failure source

var failure: Failure?

What start() threw, when it did.

Structure

SessionDiagnosticReport.Startup.Checkpoint

struct Checkpoint

No documentation comment in the source.

Instance properties

phase source

var phase: String

sourceOpened, streamInfoResolved, segmentPlanReady, firstVideoSegmentWritten or playlistServable.

elapsedSeconds source

var elapsedSeconds: Double

No documentation comment in the source.

Structure

SessionDiagnosticReport.Startup.Plan

struct Plan

The plan's shape — what a stall report needs to tell "the planner promised one segment for the rest of the film" from a slow origin.

Instance properties

basis source

var basis: String

keyframeIndex, uniform.budgetExpired, uniform.untrustedIndex or uniform.noIndex.

segments source

var segments: Int

No documentation comment in the source.

maxSegmentSeconds source

var maxSegmentSeconds: Double

The built plan's longest entry — the playlist's largest EXTINF only when the plan was published (keyframeIndex); a uniform plan runs sequential and cuts at real keyframes.

tailStartSeconds source

var tailStartSeconds: Double

The last entry, which runs to the container's end.

tailSeconds source

var tailSeconds: Double

No documentation comment in the source.

indexCoversEnd source

var indexCoversEnd: Bool?

Whether the keyframe map reached the source's end at its own cadence (the strict test); nil with no keyframes at all. A whole index ending on a long final GOP can plan with false.

indexBudgetExpired source