YouTube Clients: Multi-Client Fallback Strategy

@Serializable
data class YouTubeClient(
    val clientName: String,        // e.g. "WEB_REMIX", "ANDROID_VR"
    val clientVersion: String,     // e.g. "1.20260114.03.00"
    val clientId: String,          // numeric client ID as a string, e.g. "67"
    val userAgent: String,         // HTTP User-Agent header value
    val osName: String? = null,
    val osVersion: String? = null,
    val deviceMake: String? = null,
    val deviceModel: String? = null,
    val androidSdkVersion: String? = null,
    val buildId: String? = null,
    val cronetVersion: String? = null,
    val packageName: String? = null,
    val friendlyName: String? = null,
    // --- Capability flags ---
    val loginSupported: Boolean = false,
    val loginRequired: Boolean = false,
    val useSignatureTimestamp: Boolean = false,
    val isEmbedded: Boolean = false,
    val useWebPoTokens: Boolean = false,
    val requirePoToken: Boolean = false,
    val includeUserAgentInContext: Boolean = false,
)

data class ContentHints(
    val isExplicit: Boolean? = null,
    val isKidsContent: Boolean? = null,
    val isLive: Boolean? = null,
    val isUploaded: Boolean? = null,
)

val strategy = ContentAwareFallbackStrategy()

// Determine content hints from your song/episode metadata
val hints = ContentHints(
    isExplicit = song.explicit,
    isLive = false,
    isUploaded = song.uploadEntityId != null,
    isKidsContent = false,
)

val clients = strategy.resolveClients(hints)

var playerResponse: PlayerResponse? = null
for (client in clients) {
    val result = runCatching {
        innerTube.player(
            client = client,
            videoId = song.id,
            playlistId = playlistId,
            signatureTimestamp = if (client.useSignatureTimestamp) currentSigTimestamp else null,
        ).body<PlayerResponse>()
    }
    val response = result.getOrNull() ?: continue
    // Check that the response actually contains usable stream URLs
    if (response.streamingData?.adaptiveFormats?.isNotEmpty() == true) {
        playerResponse = response
        break
    }
}

if (playerResponse == null) {
    error("No client could resolve streams for video ${song.id}")
}