Skip to content

StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.

feat: add subtitle offset adjustment and local subtitle loading functionality

David Nashashcceb10c63d05
diff --git a/app/src/androidTest/java/com/streamvault/app/ui/PlayerSmokeTest.kt b/app/src/androidTest/java/com/streamvault/app/ui/PlayerSmokeTest.kt
index 1056cd85..4b7f7847 100644
--- a/app/src/androidTest/java/com/streamvault/app/ui/PlayerSmokeTest.kt
+++ b/app/src/androidTest/java/com/streamvault/app/ui/PlayerSmokeTest.kt
@@ -15,6 +15,7 @@ import androidx.compose.ui.test.performTextInput
import androidx.test.ext.junit.runners.AndroidJUnit4
import com.streamvault.app.ui.components.shell.CategoryRailPanel
import com.streamvault.feature.playback.player.overlay.PlayerControlsOverlay
+import com.streamvault.feature.playback.player.overlay.PlayerSubtitleOffsetDialog
import com.streamvault.feature.playback.player.overlay.PlayerTrackSelectionDialog
import com.streamvault.app.ui.test.TestFixtures
import com.streamvault.core.ui.theme.StreamVaultTheme
@@ -178,4 +179,47 @@ class PlayerSmokeTest {
check(selectedTrackId == "audio-es")
}
}
+
+ @Test
+ fun playerTrackSelectionDialog_offersLocalSubtitleAndTimingWithoutEmbeddedTracks() {
+ composeRule.setContent {
+ StreamVaultTheme {
+ PlayerTrackSelectionDialog(
+ trackType = TrackType.TEXT,
+ audioTracks = emptyList(),
+ subtitleTracks = emptyList(),
+ videoTracks = emptyList(),
+ subtitleOffsetMs = 0,
+ onDismiss = {},
+ onSelectAudio = {},
+ onSelectVideo = {},
+ onSelectSubtitle = {},
+ onOpenSubtitleOffset = {},
+ onLoadLocalSubtitle = {}
+ )
+ }
+ }
+
+ composeRule.onNodeWithText("Subtitle delay (+0 ms)").assertExists()
+ composeRule.onNodeWithText("Load SRT from device").assertExists()
+ }
+
+ @Test
+ fun playerSubtitleOffsetDialog_usesNegativeForEarlierAndPositiveForLater() {
+ composeRule.setContent {
+ StreamVaultTheme {
+ PlayerSubtitleOffsetDialog(
+ visible = true,
+ offsetMs = -200,
+ onDismiss = {},
+ onAdjust = {},
+ onReset = {}
+ )
+ }
+ }
+
+ composeRule.onNodeWithText("Current delay: -200 ms").assertExists()
+ composeRule.onNodeWithText("Show subtitles 100 ms earlier").assertExists()
+ composeRule.onNodeWithText("Show subtitles 100 ms later").assertExists()
+ }
}
diff --git a/app/src/main/java/com/streamvault/app/di/NetworkModule.kt b/app/src/main/java/com/streamvault/app/di/NetworkModule.kt
index 897fb588..5062f9d1 100644
--- a/app/src/main/java/com/streamvault/app/di/NetworkModule.kt
+++ b/app/src/main/java/com/streamvault/app/di/NetworkModule.kt
@@ -10,6 +10,7 @@ import com.streamvault.data.remote.NetworkTimeoutConfig
import com.streamvault.data.remote.http.DefaultUserAgentInterceptor
import com.streamvault.data.remote.http.buildAppRequestProfile
import com.streamvault.data.remote.http.buildAppUserAgent
+import com.streamvault.data.remote.http.buildOpenSubtitlesUserAgent
import com.streamvault.data.remote.stalker.OkHttpStalkerApiService
import com.streamvault.data.remote.stalker.StalkerApiService
import com.streamvault.data.remote.xtream.XtreamApiService
@@ -46,6 +47,10 @@ object NetworkModule {
@Named("opensubtitlesApiKey")
fun provideOpenSubtitlesApiKey(): String = BuildConfig.OPENSUBTITLES_API_KEY
+ @Provides
+ @Named("opensubtitlesUserAgent")
+ fun provideOpenSubtitlesUserAgent(): String = buildOpenSubtitlesUserAgent(BuildConfig.VERSION_NAME)
+
@Provides
@Singleton
fun provideOkHttpClient(
diff --git a/data/src/main/java/com/streamvault/data/remote/http/RequestIdentity.kt b/data/src/main/java/com/streamvault/data/remote/http/RequestIdentity.kt
index 7e2a5f4a..97456688 100644
--- a/data/src/main/java/com/streamvault/data/remote/http/RequestIdentity.kt
+++ b/data/src/main/java/com/streamvault/data/remote/http/RequestIdentity.kt
@@ -80,6 +80,11 @@ fun buildAppUserAgent(versionName: String?): String {
return "StreamVault/$normalizedVersion (Android; Media3; OkHttp)"
}
+fun buildOpenSubtitlesUserAgent(versionName: String?): String {
+ val normalizedVersion = versionName?.trim().orEmpty().ifBlank { "dev" }
+ return "StreamVault v$normalizedVersion"
+}
+
fun buildAppRequestProfile(
versionName: String?,
ownerTag: String
diff --git a/data/src/main/java/com/streamvault/data/remote/subtitle/OpenSubtitlesApi.kt b/data/src/main/java/com/streamvault/data/remote/subtitle/OpenSubtitlesApi.kt
index 30f24ccf..59973b4d 100644
--- a/data/src/main/java/com/streamvault/data/remote/subtitle/OpenSubtitlesApi.kt
+++ b/data/src/main/java/com/streamvault/data/remote/subtitle/OpenSubtitlesApi.kt
@@ -11,6 +11,9 @@ import javax.inject.Named
import javax.inject.Singleton
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
import kotlinx.coroutines.withContext
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
@@ -26,7 +29,11 @@ class OpenSubtitlesApi @Inject constructor(
private val okHttpClient: OkHttpClient,
private val gson: Gson,
@param:Named("opensubtitlesApiKey") private val apiKey: String,
+ @param:Named("opensubtitlesUserAgent") private val userAgent: String = "StreamVault vdev",
) {
+ private val loginRequestMutex = Mutex()
+ private var lastLoginRequestStartedAtNanos: Long? = null
+
data class DownloadLink(
val url: String,
val fileName: String,
@@ -63,7 +70,17 @@ class OpenSubtitlesApi @Inject constructor(
password: String,
baseUrl: String = OPENSUBTITLES_DEFAULT_BASE_URL,
): Result<OpenSubtitlesSession> = try {
- val session = withContext(Dispatchers.IO) { loginSession(username, password, baseUrl) }
+ val session = loginRequestMutex.withLock {
+ val previousStart = lastLoginRequestStartedAtNanos
+ if (previousStart != null) {
+ val remainingNanos = MIN_LOGIN_INTERVAL_NANOS - (System.nanoTime() - previousStart)
+ if (remainingNanos > 0L) {
+ delay(TimeUnit.NANOSECONDS.toMillis(remainingNanos) + 1L)
+ }
+ }
+ lastLoginRequestStartedAtNanos = System.nanoTime()
+ withContext(Dispatchers.IO) { loginSession(username, password, baseUrl) }
+ }
Result.success(session)
} catch (e: Exception) {
if (e is CancellationException) throw e
@@ -77,7 +94,7 @@ class OpenSubtitlesApi @Inject constructor(
.header("Accept", "application/json")
.header("Api-Key", requireApiKey())
.header("Authorization", "Bearer $token")
- .header("User-Agent", USER_AGENT)
+ .header("User-Agent", userAgent)
.delete()
.build()
execute(request, "OpenSubtitles logout")
@@ -90,16 +107,16 @@ class OpenSubtitlesApi @Inject constructor(
suspend fun search(
query: SearchQuery,
- token: String,
- baseUrlHost: String,
+ token: String? = null,
+ baseUrlHost: String = OPENSUBTITLES_DEFAULT_BASE_HOST,
): Result<List<OpenSubtitlesSubtitleDto>> = try {
val subtitles = withContext(Dispatchers.IO) {
val request = Request.Builder()
.url(buildUrl(baseUrlHost, "/subtitles", query.toQueryParams()))
.header("Accept", "application/json")
.header("Api-Key", requireApiKey())
- .header("Authorization", "Bearer $token")
- .header("User-Agent", USER_AGENT)
+ .header("User-Agent", userAgent)
+ .apply { token?.trim()?.takeIf { it.isNotEmpty() }?.let { header("Authorization", "Bearer $it") } }
.get()
.build()
val body = execute(request, "OpenSubtitles search")
@@ -113,8 +130,8 @@ class OpenSubtitlesApi @Inject constructor(
suspend fun downloadLink(
fileId: Long,
- token: String,
- baseUrlHost: String,
+ token: String? = null,
+ baseUrlHost: String = OPENSUBTITLES_DEFAULT_BASE_HOST,
subFormat: String = "srt",
): Result<DownloadLink> = try {
val link = withContext(Dispatchers.IO) {
@@ -124,8 +141,8 @@ class OpenSubtitlesApi @Inject constructor(
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.header("Api-Key", requireApiKey())
- .header("Authorization", "Bearer $token")
- .header("User-Agent", USER_AGENT)
+ .header("User-Agent", userAgent)
+ .apply { token?.trim()?.takeIf { it.isNotEmpty() }?.let { header("Authorization", "Bearer $it") } }
.post(payload.toRequestBody("application/json".toMediaType()))
.build()
val body = execute(request, "OpenSubtitles download")
@@ -153,7 +170,7 @@ class OpenSubtitlesApi @Inject constructor(
try {
val request = Request.Builder()
.url(link.url)
- .header("User-Agent", USER_AGENT)
+ .header("User-Agent", userAgent)
.get()
.build()
// OpenSubtitles links contain short-lived download tokens in their URL. Keep the
@@ -206,7 +223,7 @@ class OpenSubtitlesApi @Inject constructor(
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.header("Api-Key", requireApiKey())
- .header("User-Agent", USER_AGENT)
+ .header("User-Agent", userAgent)
.post(payload.toRequestBody("application/json".toMediaType()))
.build()
val body = execute(request, "OpenSubtitles login")
@@ -248,7 +265,7 @@ class OpenSubtitlesApi @Inject constructor(
} else {
"https://$normalized"
}
- val qs = query.entries.joinToString("&") { (k, v) -> "${enc(k)}=${enc(v)}" }
+ val qs = query.toSortedMap().entries.joinToString("&") { (k, v) -> "${enc(k)}=${enc(v)}" }
return "$host/api/v1$path${if (qs.isNotBlank()) "?$qs" else ""}"
}
@@ -260,7 +277,7 @@ class OpenSubtitlesApi @Inject constructor(
)
private companion object {
- const val USER_AGENT = "StreamVault v1"
const val REQUEST_TIMEOUT_SECONDS = 30L
+ const val MIN_LOGIN_INTERVAL_NANOS = 1_000_000_000L
}
}
diff --git a/data/src/main/java/com/streamvault/data/repository/OpenSubtitlesRepositoryImpl.kt b/data/src/main/java/com/streamvault/data/repository/OpenSubtitlesRepositoryImpl.kt
index 4c5fab6f..33170e85 100644
--- a/data/src/main/java/com/streamvault/data/repository/OpenSubtitlesRepositoryImpl.kt
+++ b/data/src/main/java/com/streamvault/data/repository/OpenSubtitlesRepositoryImpl.kt
@@ -7,6 +7,7 @@ import com.streamvault.data.remote.subtitle.OpenSubtitlesCredentials
import com.streamvault.data.remote.subtitle.OpenSubtitlesSession
import com.streamvault.data.remote.subtitle.OpenSubtitlesSessionStore
import com.streamvault.data.remote.subtitle.OpenSubtitlesSubtitleDto
+import com.streamvault.data.remote.subtitle.OPENSUBTITLES_DEFAULT_BASE_HOST
import com.streamvault.domain.manager.OpenSubtitlesAccount
import com.streamvault.domain.manager.OpenSubtitlesAccountManager
import com.streamvault.domain.model.ContentType
@@ -84,7 +85,13 @@ class OpenSubtitlesRepositoryImpl @Inject constructor(
language: String,
): Result<List<ExternalSubtitle>> = try {
val query = buildSearchQuery(contentType, title, year, tmdbId, parentTmdbId, seasonNumber, episodeNumber, language)
- authenticatedRequest { session -> api.search(query, session.token, session.baseUrl) }
+ requestWithOptionalSession { session ->
+ api.search(
+ query = query,
+ token = session?.token,
+ baseUrlHost = session?.baseUrl ?: OPENSUBTITLES_DEFAULT_BASE_HOST,
+ )
+ }
.map { subtitles -> subtitles.mapNotNull(::mapSubtitle) }
} catch (e: Exception) {
if (e is CancellationException) throw e
@@ -98,14 +105,20 @@ class OpenSubtitlesRepositoryImpl @Inject constructor(
val destination = subtitleCacheFile(fileId)
if (destination.isFile && destination.length() > 0L) return Result.success(destination)
- authenticatedRequest { session ->
- if (session.remainingDownloads == 0) {
- return@authenticatedRequest Result.error("Your OpenSubtitles download allowance is used for today.")
+ requestWithOptionalSession { session ->
+ if (session?.remainingDownloads == 0) {
+ return@requestWithOptionalSession Result.error("Your OpenSubtitles download allowance is used for today.")
}
- when (val link = api.downloadLink(fileId, session.token, session.baseUrl)) {
+ when (val link = api.downloadLink(
+ fileId = fileId,
+ token = session?.token,
+ baseUrlHost = session?.baseUrl ?: OPENSUBTITLES_DEFAULT_BASE_HOST,
+ )) {
is Result.Success -> {
- link.data.remaining?.let { remaining ->
- sessionStore.updateRemainingDownloads(remaining, link.data.resetTimeUtc)
+ if (session != null) {
+ link.data.remaining?.let { remaining ->
+ sessionStore.updateRemainingDownloads(remaining, link.data.resetTimeUtc)
+ }
}
api.downloadSubtitleFile(link.data, destination)
}
@@ -119,18 +132,27 @@ class OpenSubtitlesRepositoryImpl @Inject constructor(
}
}
- private suspend fun <T> authenticatedRequest(
- request: suspend (OpenSubtitlesSession) -> Result<T>,
+ private suspend fun <T> requestWithOptionalSession(
+ request: suspend (OpenSubtitlesSession?) -> Result<T>,
): Result<T> {
- val initial = obtainSession()
- val session = initial.getOrNull() ?: return initial.asError("Sign in to OpenSubtitles in Settings to search for subtitles.")
+ val initial = obtainOptionalSession()
+ val session = when (initial) {
+ is Result.Success -> initial.data
+ is Result.Error -> return initial
+ is Result.Loading -> return Result.Loading
+ }
val response = request(session)
- if (!response.isUnauthorized()) return response
+ if (session == null || !response.isUnauthorized()) return response
val refreshed = refreshSession(rejectedToken = session.token)
- val refreshedSession = refreshed.getOrNull() ?: return refreshed.asError(
- "Your OpenSubtitles session expired. Sign in again in Settings."
- )
+ val refreshedSession = when (refreshed) {
+ is Result.Success -> refreshed.data
+ is Result.Error -> return Result.error(
+ "Your OpenSubtitles session expired. Sign in again in Settings.",
+ refreshed.exception,
+ )
+ is Result.Loading -> return Result.Loading
+ }
val retry = request(refreshedSession)
if (retry.isUnauthorized()) invalidateRejectedSession(refreshedSession.token)
return retry
@@ -142,11 +164,11 @@ class OpenSubtitlesRepositoryImpl @Inject constructor(
}
}
- private suspend fun obtainSession(): Result<OpenSubtitlesSession> = sessionMutex.withLock {
+ private suspend fun obtainOptionalSession(): Result<OpenSubtitlesSession?> = sessionMutex.withLock {
sessionStore.loadSession()?.let { return@withLock Result.success(it) }
val credentials = sessionStore.loadCredentials()
- ?: return@withLock Result.error(NOT_SIGNED_IN_MESSAGE)
- loginAndStore(credentials)
+ ?: return@withLock Result.success(null)
+ loginAndStore(credentials).map { it }
}
/** Reuses a token another concurrent request has already refreshed. */
@@ -260,12 +282,6 @@ class OpenSubtitlesRepositoryImpl @Inject constructor(
private fun Throwable?.isUnauthorized(): Boolean =
this is OpenSubtitlesApiException && isUnauthorized
- private fun <T> Result<*>.asError(fallbackMessage: String): Result<T> = when (this) {
- is Result.Error -> Result.error(message, exception)
- is Result.Loading -> Result.error(fallbackMessage)
- is Result.Success -> Result.error(fallbackMessage)
- }
-
private fun OpenSubtitlesSession.toAccount() = OpenSubtitlesAccount(
username = username,
allowedDownloads = allowedDownloads,
@@ -274,8 +290,4 @@ class OpenSubtitlesRepositoryImpl @Inject constructor(
vip = vip,
)
- private companion object {
- const val NOT_SIGNED_IN_MESSAGE =
- "OpenSubtitles is not signed in. Add your OpenSubtitles.com account in Settings."
- }
}
diff --git a/data/src/test/java/com/streamvault/data/remote/http/RequestIdentityTest.kt b/data/src/test/java/com/streamvault/data/remote/http/RequestIdentityTest.kt
index e1d09e1e..7778413b 100644
--- a/data/src/test/java/com/streamvault/data/remote/http/RequestIdentityTest.kt
+++ b/data/src/test/java/com/streamvault/data/remote/http/RequestIdentityTest.kt
@@ -19,6 +19,12 @@ class RequestIdentityTest {
assertThat(request.header(USER_AGENT_HEADER)).isEqualTo("ExplicitAgent/1.0")
}
+ @Test
+ fun `OpenSubtitles user agent follows app name and version format`() {
+ assertThat(buildOpenSubtitlesUserAgent("1.2.3")).isEqualTo("StreamVault v1.2.3")
+ assertThat(buildOpenSubtitlesUserAgent(null)).isEqualTo("StreamVault vdev")
+ }
+
@Test
fun `safeRequestIdentitySummary redacts sensitive headers`() {
val request = Request.Builder()
@@ -60,4 +66,4 @@ class RequestIdentityTest {
"Accept-Language", "en-US"
)
}
-}
\ No newline at end of file
+}
diff --git a/data/src/test/java/com/streamvault/data/remote/subtitle/OpenSubtitlesApiDownloadTest.kt b/data/src/test/java/com/streamvault/data/remote/subtitle/OpenSubtitlesApiDownloadTest.kt
index 7f4fcef1..c63967b0 100644
--- a/data/src/test/java/com/streamvault/data/remote/subtitle/OpenSubtitlesApiDownloadTest.kt
+++ b/data/src/test/java/com/streamvault/data/remote/subtitle/OpenSubtitlesApiDownloadTest.kt
@@ -42,6 +42,29 @@ class OpenSubtitlesApiDownloadTest {
}
}
+ @Test
+ fun `login requests are spaced to respect the API rate limit`() = runBlocking {
+ val server = MockWebServer()
+ server.start()
+ try {
+ repeat(2) {
+ server.enqueue(MockResponse().setBody("""{"token":"test-token"}"""))
+ }
+ val api = OpenSubtitlesApi(OkHttpClient(), Gson(), "test-api-key")
+ val baseUrl = server.url("/api/v1").toString().trimEnd('/')
+
+ val firstStartedAt = System.nanoTime()
+ assertThat(api.login("test-user", "test-password", baseUrl).isSuccess).isTrue()
+ assertThat(api.login("test-user", "test-password", baseUrl).isSuccess).isTrue()
+
+ val elapsedMillis = (System.nanoTime() - firstStartedAt) / 1_000_000L
+ assertThat(elapsedMillis).isAtLeast(950L)
+ assertThat(server.requestCount).isEqualTo(2)
+ } finally {
+ server.shutdown()
+ }
+ }
+
@Test
fun `missing application key returns setup guidance without a request`() = runBlocking {
val server = MockWebServer()
@@ -59,6 +82,81 @@ class OpenSubtitlesApiDownloadTest {
}
}
+ @Test
+ fun `search sends the app key and only sends bearer when an account token exists`() = runBlocking {
+ val server = MockWebServer()
+ server.start()
+ try {
+ server.enqueue(MockResponse().setBody("""{"data":[]}"""))
+ server.enqueue(MockResponse().setBody("""{"data":[]}"""))
+ val api = OpenSubtitlesApi(OkHttpClient(), Gson(), "test-api-key")
+ val baseUrl = server.url("/").toString().trimEnd('/')
+
+ assertThat(api.search(OpenSubtitlesApi.SearchQuery(query = "Alien"), baseUrlHost = baseUrl).isSuccess)
+ .isTrue()
+ assertThat(api.search(
+ OpenSubtitlesApi.SearchQuery(query = "Alien"),
+ token = "user-token",
+ baseUrlHost = baseUrl,
+ ).isSuccess).isTrue()
+
+ val anonymous = server.takeRequest()
+ assertThat(anonymous.getHeader("Api-Key")).isEqualTo("test-api-key")
+ assertThat(anonymous.getHeader("Authorization")).isNull()
+ assertThat(anonymous.getHeader("User-Agent")).isEqualTo("StreamVault vdev")
+ val authenticated = server.takeRequest()
+ assertThat(authenticated.getHeader("Api-Key")).isEqualTo("test-api-key")
+ assertThat(authenticated.getHeader("Authorization")).isEqualTo("Bearer user-token")
+ } finally {
+ server.shutdown()
+ }
+ }
+
+ @Test
+ fun `search sorts query parameters and encodes spaces with plus`() = runBlocking {
+ val server = MockWebServer()
+ server.start()
+ try {
+ server.enqueue(MockResponse().setBody("""{"data":[]}"""))
+ val api = OpenSubtitlesApi(OkHttpClient(), Gson(), "test-api-key")
+
+ val result = api.search(
+ OpenSubtitlesApi.SearchQuery(query = "Star Trek", tmdbId = 42L, languages = "en"),
+ baseUrlHost = server.url("/").toString().trimEnd('/'),
+ )
+
+ assertThat(result.isSuccess).isTrue()
+ assertThat(server.takeRequest().path)
+ .isEqualTo("/api/v1/subtitles?languages=en&query=Star+Trek&tmdb_id=42")
+ } finally {
+ server.shutdown()
+ }
+ }
+
+ @Test
+ fun `anonymous download request includes the app key without a bearer token`() = runBlocking {
+ val server = MockWebServer()
+ server.start()
+ try {
+ server.enqueue(MockResponse().setBody(
+ """{"link":"https://example.com/file.srt","file_name":"file.srt","remaining":4}"""
+ ))
+ val api = OpenSubtitlesApi(OkHttpClient(), Gson(), "test-api-key")
+
+ val result = api.downloadLink(
+ fileId = 42L,
+ baseUrlHost = server.url("/").toString().trimEnd('/'),
+ )
+
+ assertThat(result.isSuccess).isTrue()
+ val request = server.takeRequest()
+ assertThat(request.getHeader("Api-Key")).isEqualTo("test-api-key")
+ assertThat(request.getHeader("Authorization")).isNull()
+ } finally {
+ server.shutdown()
+ }
+ }
+
@Test
fun `temporary link token is not written to network logs and file is committed`() = runBlocking {
val server = MockWebServer()
diff --git a/docs/OPENSUBTITLES_INTEGRATION.md b/docs/OPENSUBTITLES_INTEGRATION.md
index 314a1f43..76bafd45 100644
--- a/docs/OPENSUBTITLES_INTEGRATION.md
+++ b/docs/OPENSUBTITLES_INTEGRATION.md
@@ -1,33 +1,33 @@
# OpenSubtitles.com integration
-The account, settings, search, download, and player-injection flows are implemented. For local debug builds, provide the OpenSubtitles application key through the ignored root `local.properties` file.
+The optional account, settings, search, download, and player-injection flows are implemented. Every OpenSubtitles API request uses the application API key. When the API consumer permits anonymous access, search and download can run without a user session; signing in adds the user's bearer token and account-specific allowance.
## User flow
-1. Open **Settings → Playback → Subtitles** and connect an OpenSubtitles.com account.
-2. During movie or series-episode playback, open **Subtitles → Search online subtitles**.
-3. Choose a result to download and add it to the current player session.
+1. During movie or series-episode playback, open **Subtitles → Search online subtitles**.
+2. Search anonymously when allowed by the app's OpenSubtitles consumer settings, or optionally connect an OpenSubtitles.com account in **Settings → Playback → Subtitles**.
+3. Choose a result to download and add it to the current player session. Anonymous downloads may be restricted by the consumer configuration or OpenSubtitles limits.
Online search is hidden for live TV and catch-up. Search uses the movie or series TMDb ID when available, title/year fallbacks for movies, season/episode metadata for episodes, and the preferred audio language (English when the preference is automatic).
## Session, quota, and downloads
- Username, password, and JWT are encrypted with the app's `CredentialCrypto`. Existing plaintext usernames are still readable for migration; new writes are encrypted.
-- Session reads, sign-in/out, and one-time refresh after HTTP 401 share a mutex. Concurrent requests reuse a token refreshed by another request. If the refreshed token also receives 401, the saved session and credentials are cleared.
-- The account page shows the daily allowance from login until a current remaining count is known. Successful `/download` responses update the remaining count, which expires at `reset_time_utc`.
+- Session reads, sign-in/out, and one-time refresh after HTTP 401 share a mutex. Login requests are spaced to respect OpenSubtitles' one-request-per-second login limit. Concurrent requests reuse a token refreshed by another request. If the refreshed token also receives 401, the saved session and credentials are cleared.
+- The account page shows the daily allowance from login until a current remaining count is known. Successful `/download` responses update the remaining count, which expires at `reset_time_utc`. The app does not hard-code an anonymous or account quota because OpenSubtitles applies limits by consumer and account.
- Subtitle files are cached by OpenSubtitles file ID. A valid cached file avoids another quota-consuming `/download` request.
- File responses are cancellable, written to a temporary file, and moved into the cache only after completion. The temporary download URL is excluded from OkHttp request logging.
- OpenSubtitles can enforce both account download allowances and request limits. The app displays the account's remaining download count when the API provides it; IP-based request limits remain controlled by OpenSubtitles.
## API key
-Add this line to the root `local.properties` file (already gitignored), then rebuild:
+Add this line to the root `local.properties` file (already gitignored), then rebuild a debug build:
```properties
opensubtitles.api.key=YOUR_OPENSUBTITLES_API_KEY
```
-The key is injected into debug builds only. If it is missing, sign-in returns setup guidance instead of sending a malformed request. The key is packaged into the app binary and can be extracted from an APK, so this local setup prevents Git exposure but does not make the key secret from app users. Account passwords and bearer tokens remain encrypted locally.
+The key is injected into debug builds only; release variants currently have an empty key. The app can still compile without a key, but OpenSubtitles requests return setup guidance and the online subtitle feature cannot work. The key is required even when no user is signed in. It is packaged into the app binary and can be extracted from an APK, so this local setup prevents Git exposure but does not make the key secret from app users. Account passwords and bearer tokens remain encrypted locally.
## Validation
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerBackNavigationPolicy.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerBackNavigationPolicy.kt
index c48bdbc1..dd527f82 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerBackNavigationPolicy.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerBackNavigationPolicy.kt
@@ -17,6 +17,7 @@ internal enum class PlayerBackAction {
CLOSE_PLAYBACK_SETTINGS,
CLOSE_SPEED_SELECTION,
CLOSE_AUDIO_VIDEO_OFFSET_DIALOG,
+ CLOSE_SUBTITLE_OFFSET_DIALOG,
CLOSE_STOP_PLAYBACK_TIMER,
CLOSE_IDLE_STANDBY_TIMER,
CLOSE_VARIANT_SELECTION,
@@ -42,6 +43,7 @@ internal data class PlayerBackNavigationState(
val showPlaybackSettings: Boolean = false,
val showSpeedSelection: Boolean = false,
val showAudioVideoOffsetDialog: Boolean = false,
+ val showSubtitleOffsetDialog: Boolean = false,
val showStopPlaybackTimerDialog: Boolean = false,
val showIdleStandbyTimerDialog: Boolean = false,
val hasTrackSelection: Boolean = false,
@@ -67,6 +69,7 @@ internal fun playerBackAction(state: PlayerBackNavigationState): PlayerBackActio
state.showPlaybackSettings -> PlayerBackAction.CLOSE_PLAYBACK_SETTINGS
state.showSpeedSelection -> PlayerBackAction.CLOSE_SPEED_SELECTION
state.showAudioVideoOffsetDialog -> PlayerBackAction.CLOSE_AUDIO_VIDEO_OFFSET_DIALOG
+ state.showSubtitleOffsetDialog -> PlayerBackAction.CLOSE_SUBTITLE_OFFSET_DIALOG
state.showStopPlaybackTimerDialog -> PlayerBackAction.CLOSE_STOP_PLAYBACK_TIMER
state.showIdleStandbyTimerDialog -> PlayerBackAction.CLOSE_IDLE_STANDBY_TIMER
state.showVariantSelection -> PlayerBackAction.CLOSE_VARIANT_SELECTION
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerExternalSubtitleActions.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerExternalSubtitleActions.kt
index 082753ca..acd6c4f0 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerExternalSubtitleActions.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerExternalSubtitleActions.kt
@@ -19,15 +19,6 @@ internal fun PlayerViewModel.searchExternalSubtitles() {
)
return
}
- if (externalSubtitleSearchStateFlow.value.account == null) {
- externalSubtitleSearchStateFlow.value = externalSubtitleSearchStateFlow.value.copy(
- isSearching = false,
- subtitles = emptyList(),
- errorMessage = null,
- )
- return
- }
-
externalSubtitleSearchJob = viewModelScope.launch {
externalSubtitleSearchStateFlow.update {
it.copy(
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerExternalSubtitleSearchDialog.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerExternalSubtitleSearchDialog.kt
index 574b686a..256344c4 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerExternalSubtitleSearchDialog.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerExternalSubtitleSearchDialog.kt
@@ -61,11 +61,9 @@ internal fun PlayerExternalSubtitleSearchDialog(
onDismiss()
}
- LaunchedEffect(state.account?.username) {
- if (state.account != null) viewModel.searchExternalSubtitles()
- }
+ LaunchedEffect(Unit) { viewModel.searchExternalSubtitles() }
LaunchedEffect(state.isSearching, state.subtitles.firstOrNull()?.id, state.account?.username) {
- if (state.account != null && !state.isSearching && state.subtitles.isNotEmpty()) {
+ if (!state.isSearching && state.subtitles.isNotEmpty()) {
firstResultFocusRequester.requestFocusSafely(
tag = "PlayerExternalSubtitleSearchDialog",
target = "First subtitle result",
@@ -104,21 +102,22 @@ internal fun PlayerExternalSubtitleSearchDialog(
)
}
- if (state.account == null) {
- Column(
- modifier = Modifier.weight(1f).fillMaxWidth(),
- verticalArrangement = Arrangement.Center,
- horizontalAlignment = Alignment.CenterHorizontally,
- ) {
- Button(onClick = onOpenSettings) {
- Text(stringResource(R.string.player_subtitle_search_open_settings))
- }
- }
- } else {
- LazyColumn(
+ LazyColumn(
modifier = Modifier.weight(1f).fillMaxWidth(),
verticalArrangement = Arrangement.spacedBy(8.dp),
) {
+ if (state.account == null) {
+ item {
+ Row(
+ modifier = Modifier.fillMaxWidth().padding(horizontal = 8.dp),
+ horizontalArrangement = Arrangement.End,
+ ) {
+ Button(onClick = onOpenSettings) {
+ Text(stringResource(R.string.player_subtitle_search_open_settings))
+ }
+ }
+ }
+ }
if (state.isSearching) {
item {
Row(
@@ -240,7 +239,6 @@ internal fun PlayerExternalSubtitleSearchDialog(
}
}
}
- }
Row(
modifier = Modifier.fillMaxWidth(),
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerInputPolicy.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerInputPolicy.kt
index 5ad6a6ef..85265247 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerInputPolicy.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerInputPolicy.kt
@@ -38,6 +38,7 @@ internal data class PlayerInputState(
val showVariantSelection: Boolean = false,
val showSpeedSelection: Boolean = false,
val showAudioVideoOffsetDialog: Boolean = false,
+ val showSubtitleOffsetDialog: Boolean = false,
val showStopPlaybackTimerDialog: Boolean = false,
val showIdleStandbyTimerDialog: Boolean = false,
val showProgramHistory: Boolean = false,
@@ -67,6 +68,7 @@ internal sealed interface PlayerInputAction {
data object PlayPrevious : PlayerInputAction
data object CancelAutoPlay : PlayerInputAction
data object DismissAudioVideoOffset : PlayerInputAction
+ data object DismissSubtitleOffset : PlayerInputAction
data object CloseSpeedSelection : PlayerInputAction
data object CloseVariantSelection : PlayerInputAction
data object CloseStopIdleTimersAndTrackSelection : PlayerInputAction
@@ -109,6 +111,7 @@ internal fun playerPreviewInputDecision(
state.showVariantSelection ||
state.showSpeedSelection ||
state.showAudioVideoOffsetDialog ||
+ state.showSubtitleOffsetDialog ||
state.showStopPlaybackTimerDialog ||
state.showIdleStandbyTimerDialog ||
state.showProgramHistory ||
@@ -150,6 +153,8 @@ internal fun playerInputDecision(
return modalInputDecision(PlayerInputAction.CancelClosePlayback, key)
state.showAudioVideoOffsetDialog ->
return modalInputDecision(PlayerInputAction.DismissAudioVideoOffset, key)
+ state.showSubtitleOffsetDialog ->
+ return modalInputDecision(PlayerInputAction.DismissSubtitleOffset, key)
state.showSpeedSelection ->
return modalInputDecision(PlayerInputAction.CloseSpeedSelection, key)
state.showVariantSelection ->
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerLocalSubtitleActions.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerLocalSubtitleActions.kt
new file mode 100644
index 00000000..de168419
--- /dev/null
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerLocalSubtitleActions.kt
@@ -0,0 +1,91 @@
+package com.streamvault.feature.playback.player
+
+import android.net.Uri
+import android.provider.OpenableColumns
+import androidx.lifecycle.viewModelScope
+import com.streamvault.feature.playback.R
+import java.io.File
+import java.io.IOException
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+
+private const val MAX_LOCAL_SUBTITLE_BYTES = 20L * 1024L * 1024L
+
+private class UnsupportedLocalSubtitleFileException : IOException()
+private class LocalSubtitleFileTooLargeException : IOException()
+
+private data class ImportedLocalSubtitle(
+ val file: File,
+ val displayName: String
+)
+
+internal fun PlayerViewModel.loadLocalSrtSubtitle(uri: Uri) {
+ viewModelScope.launch {
+ try {
+ val subtitle = withContext(Dispatchers.IO) { copyLocalSrtSubtitle(uri) }
+ deactivateLiveTranslation()
+ playerEngine.addExternalSubtitle(
+ subtitleUri = Uri.fromFile(subtitle.file),
+ language = "und",
+ label = subtitle.displayName
+ )
+ showPlayerNotice(
+ appContext.getString(R.string.player_subtitle_loaded, subtitle.displayName)
+ )
+ } catch (cancelled: CancellationException) {
+ throw cancelled
+ } catch (_: UnsupportedLocalSubtitleFileException) {
+ showPlayerNotice(appContext.getString(R.string.player_subtitle_invalid_file))
+ } catch (_: LocalSubtitleFileTooLargeException) {
+ showPlayerNotice(appContext.getString(R.string.player_subtitle_file_too_large))
+ } catch (_: Exception) {
+ showPlayerNotice(appContext.getString(R.string.player_subtitle_load_failed))
+ }
+ }
+}
+
+private fun PlayerViewModel.copyLocalSrtSubtitle(uri: Uri): ImportedLocalSubtitle {
+ val resolver = appContext.contentResolver
+ val displayName = resolver.query(
+ uri,
+ arrayOf(OpenableColumns.DISPLAY_NAME),
+ null,
+ null,
+ null
+ )?.use { cursor ->
+ val nameColumn = cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME)
+ if (nameColumn >= 0 && cursor.moveToFirst()) cursor.getString(nameColumn) else null
+ } ?: uri.lastPathSegment?.substringAfterLast('/') ?: "subtitle.srt"
+
+ if (!displayName.substringAfterLast('.', missingDelimiterValue = "").equals("srt", ignoreCase = true)) {
+ throw UnsupportedLocalSubtitleFileException()
+ }
+
+ val file = File.createTempFile("streamvault-subtitle-", ".srt", appContext.cacheDir)
+ try {
+ val input = resolver.openInputStream(uri) ?: throw IOException("Unable to open selected subtitle")
+ var copiedBytes = 0L
+ input.use { source ->
+ file.outputStream().buffered().use { destination ->
+ val buffer = ByteArray(DEFAULT_BUFFER_SIZE)
+ while (true) {
+ val count = source.read(buffer)
+ if (count < 0) break
+ if (count == 0) continue
+ copiedBytes += count
+ if (copiedBytes > MAX_LOCAL_SUBTITLE_BYTES) {
+ throw LocalSubtitleFileTooLargeException()
+ }
+ destination.write(buffer, 0, count)
+ }
+ }
+ }
+ if (copiedBytes == 0L) throw IOException("Selected subtitle file is empty")
+ return ImportedLocalSubtitle(file = file, displayName = displayName)
+ } catch (failure: Throwable) {
+ file.delete()
+ throw failure
+ }
+}
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerModalHosts.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerModalHosts.kt
index b5c25793..612e7b29 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerModalHosts.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerModalHosts.kt
@@ -13,6 +13,7 @@ import com.streamvault.feature.playback.player.overlay.PlayerAudioVideoOffsetDia
import com.streamvault.feature.playback.player.overlay.PlayerEpisodeSelectionDialog
import com.streamvault.feature.playback.player.overlay.PlayerSleepTimerDialog
import com.streamvault.feature.playback.player.overlay.PlayerSpeedSelectionDialog
+import com.streamvault.feature.playback.player.overlay.PlayerSubtitleOffsetDialog
import com.streamvault.feature.playback.player.overlay.PlayerTrackSelectionDialog
import com.streamvault.domain.model.Channel
import com.streamvault.domain.model.Episode
@@ -60,11 +61,14 @@ internal fun PlayerControlsModalHost(
showIdleStandbyTimerDialog: Boolean,
canSaveChannel: Boolean,
showAudioVideoOffsetDialog: Boolean,
+ showSubtitleOffsetDialog: Boolean,
showEpisodePicker: Boolean,
fallbackTitle: String,
fallbackEpisodeId: Long,
fallbackSeasonNumber: Int?,
onOpenSubtitleSearch: () -> Unit,
+ onOpenSubtitleOffset: () -> Unit,
+ onPickLocalSubtitle: () -> Unit,
onOpenSettings: () -> Unit,
onDismissModal: () -> Unit,
) {
@@ -102,6 +106,7 @@ internal fun PlayerControlsModalHost(
val availableVideoQualities by viewModel.availableVideoQualities.collectAsStateWithLifecycle()
val liveTranslationAvailable by viewModel.liveTranslationAvailable.collectAsStateWithLifecycle()
val liveTranslationActive by viewModel.liveTranslationActive.collectAsStateWithLifecycle()
+ val subtitleOffsetMs by viewModel.subtitleOffsetMs.collectAsStateWithLifecycle()
PlayerTrackSelectionDialog(
trackType = showTrackSelection,
audioTracks = availableAudioTracks,
@@ -110,6 +115,7 @@ internal fun PlayerControlsModalHost(
liveTranslationAvailable = liveTranslationAvailable,
liveTranslationActive = liveTranslationActive,
onlineSubtitleSearchAvailable = onlineSubtitleSearchAvailable,
+ subtitleOffsetMs = subtitleOffsetMs,
onDismiss = onDismissModal,
onSelectAudio = viewModel::selectAudioTrack,
onSelectVideo = viewModel::selectVideoQuality,
@@ -122,6 +128,21 @@ internal fun PlayerControlsModalHost(
viewModel.activateLiveTranslation()
},
onSearchOnlineSubtitles = onOpenSubtitleSearch,
+ onOpenSubtitleOffset = onOpenSubtitleOffset,
+ onLoadLocalSubtitle = {
+ onDismissModal()
+ onPickLocalSubtitle()
+ },
+ )
+ }
+ if (!isInPictureInPictureMode && showSubtitleOffsetDialog) {
+ val subtitleOffsetMs by viewModel.subtitleOffsetMs.collectAsStateWithLifecycle()
+ PlayerSubtitleOffsetDialog(
+ visible = true,
+ offsetMs = subtitleOffsetMs,
+ onDismiss = onDismissModal,
+ onAdjust = viewModel::adjustSubtitleOffset,
+ onReset = viewModel::resetSubtitleOffset
)
}
if (!isInPictureInPictureMode && showSubtitleSearch) {
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerModalState.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerModalState.kt
index 1ce5caa3..f9a44b8d 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerModalState.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerModalState.kt
@@ -7,6 +7,7 @@ internal sealed interface PlayerModal {
data object VariantSelection : PlayerModal
data object SpeedSelection : PlayerModal
data object AudioVideoOffset : PlayerModal
+ data object SubtitleOffset : PlayerModal
data object StopPlaybackTimer : PlayerModal
data object IdleStandbyTimer : PlayerModal
data object ProgramHistory : PlayerModal
@@ -37,6 +38,9 @@ internal data class PlayerModalState(
val showAudioVideoOffsetDialog: Boolean
get() = active is PlayerModal.AudioVideoOffset
+ val showSubtitleOffsetDialog: Boolean
+ get() = active is PlayerModal.SubtitleOffset
+
val showStopPlaybackTimerDialog: Boolean
get() = active is PlayerModal.StopPlaybackTimer
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerPlaybackPreferenceActions.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerPlaybackPreferenceActions.kt
index 999112bd..d9842e97 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerPlaybackPreferenceActions.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerPlaybackPreferenceActions.kt
@@ -9,6 +9,8 @@ import com.streamvault.domain.settings.VodTrackPreference
import com.streamvault.domain.settings.VodTrackPreferences
import com.streamvault.player.AUDIO_VIDEO_OFFSET_MAX_MS
import com.streamvault.player.AUDIO_VIDEO_OFFSET_MIN_MS
+import com.streamvault.player.SUBTITLE_OFFSET_MAX_MS
+import com.streamvault.player.SUBTITLE_OFFSET_MIN_MS
import com.streamvault.player.PlaybackState
import com.streamvault.player.PlayerError
import kotlinx.coroutines.delay
@@ -263,6 +265,15 @@ fun PlayerViewModel.resetAudioVideoOffsetPreview() {
previewAudioVideoOffset(0)
}
+fun PlayerViewModel.adjustSubtitleOffset(deltaMs: Int) {
+ val current = subtitleOffsetMs.value
+ playerEngine.setSubtitleOffsetMs((current + deltaMs).coerceIn(SUBTITLE_OFFSET_MIN_MS, SUBTITLE_OFFSET_MAX_MS))
+}
+
+fun PlayerViewModel.resetSubtitleOffset() {
+ playerEngine.setSubtitleOffsetMs(0)
+}
+
fun PlayerViewModel.dismissAudioVideoOffsetPreview() {
audioVideoOffsetPreviewMs.value = null
}
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerScreen.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerScreen.kt
index 78a5d8fb..c29a5db6 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerScreen.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerScreen.kt
@@ -1,6 +1,8 @@
package com.streamvault.feature.playback.player
import android.view.KeyEvent
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
import androidx.activity.compose.BackHandler
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.*
@@ -179,6 +181,14 @@ fun PlayerScreen(
val preventStandbyDuringPlayback by viewModel.preventStandbyDuringPlayback.collectAsStateWithLifecycle()
val sleepTimerExitEvent by viewModel.sleepTimerExitEvent.collectAsStateWithLifecycle()
val playerPreferences by viewModel.playerPreferencesUiState.collectAsStateWithLifecycle()
+ val localSubtitlePicker = rememberLauncherForActivityResult(
+ contract = ActivityResultContracts.OpenDocument()
+ ) { uri ->
+ uri?.let(viewModel::loadLocalSrtSubtitle)
+ }
+ val pickLocalSubtitle: () -> Unit = {
+ localSubtitlePicker.launch(arrayOf("application/x-subrip", "text/plain", "application/octet-stream"))
+ }
DisposableEffect(viewModel) {
onDispose { viewModel.clearSeekPreview() }
@@ -445,6 +455,7 @@ fun PlayerScreen(
showPlaybackSettings = modalState.showPlaybackSettings,
showSpeedSelection = modalState.showSpeedSelection,
showAudioVideoOffsetDialog = modalState.showAudioVideoOffsetDialog,
+ showSubtitleOffsetDialog = modalState.showSubtitleOffsetDialog,
showStopPlaybackTimerDialog = modalState.showStopPlaybackTimerDialog,
showIdleStandbyTimerDialog = modalState.showIdleStandbyTimerDialog,
hasTrackSelection = modalState.trackSelection != null,
@@ -471,6 +482,7 @@ fun PlayerScreen(
modalState = modalState.dismiss()
viewModel.dismissAudioVideoOffsetPreview()
}
+ PlayerBackAction.CLOSE_SUBTITLE_OFFSET_DIALOG -> modalState = modalState.dismiss()
PlayerBackAction.CLOSE_STOP_PLAYBACK_TIMER -> modalState = modalState.dismiss()
PlayerBackAction.CLOSE_IDLE_STANDBY_TIMER -> modalState = modalState.dismiss()
PlayerBackAction.CLOSE_VARIANT_SELECTION -> modalState = modalState.dismiss()
@@ -514,6 +526,7 @@ fun PlayerScreen(
showVariantSelection = modalState.showVariantSelection,
showSpeedSelection = modalState.showSpeedSelection,
showAudioVideoOffsetDialog = modalState.showAudioVideoOffsetDialog,
+ showSubtitleOffsetDialog = modalState.showSubtitleOffsetDialog,
showStopPlaybackTimerDialog = modalState.showStopPlaybackTimerDialog,
showIdleStandbyTimerDialog = modalState.showIdleStandbyTimerDialog,
showProgramHistory = modalState.showProgramHistory,
@@ -609,6 +622,10 @@ fun PlayerScreen(
viewModel.dismissAudioVideoOffsetPreview()
true
}
+ PlayerInputAction.DismissSubtitleOffset -> {
+ modalState = modalState.dismiss()
+ true
+ }
PlayerInputAction.CloseSpeedSelection -> {
modalState = modalState.dismiss()
true
@@ -952,11 +969,14 @@ fun PlayerScreen(
showIdleStandbyTimerDialog = modalState.showIdleStandbyTimerDialog,
canSaveChannel = currentChannel != null,
showAudioVideoOffsetDialog = modalState.showAudioVideoOffsetDialog,
+ showSubtitleOffsetDialog = modalState.showSubtitleOffsetDialog,
showEpisodePicker = modalState.showEpisodePicker,
fallbackTitle = title,
fallbackEpisodeId = internalChannelId,
fallbackSeasonNumber = seasonNumber,
onOpenSubtitleSearch = { modalState = modalState.open(PlayerModal.SubtitleSearch) },
+ onOpenSubtitleOffset = { modalState = modalState.open(PlayerModal.SubtitleOffset) },
+ onPickLocalSubtitle = pickLocalSubtitle,
onOpenSettings = { onNavigate?.invoke(AppDestination.Settings()) },
onDismissModal = { modalState = modalState.dismiss() }
)
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerViewModel.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerViewModel.kt
index b9741a9a..eb102417 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerViewModel.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/PlayerViewModel.kt
@@ -974,6 +974,7 @@ class PlayerViewModel @Inject constructor(
val mediaTitle: StateFlow<String?> = activeEngineState<String?>(null) { it.mediaTitle }
val playbackSpeed: StateFlow<Float> = activeEngineState(1f) { it.playbackSpeed }
val audioVideoSyncEnabled: StateFlow<Boolean> = activeEngineState(false) { it.audioVideoSyncEnabled }
+ val subtitleOffsetMs: StateFlow<Int> = activeEngineState(0) { it.subtitleOffsetMs }
val preventStandbyDuringPlayback: StateFlow<Boolean> by lazy(LazyThreadSafetyMode.NONE) {
playerPreferencesCoordinator.preventStandbyDuringPlayback
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/VodOverlayState.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/VodOverlayState.kt
index 62587365..c985f856 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/VodOverlayState.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/VodOverlayState.kt
@@ -30,6 +30,7 @@ internal fun buildVodOverlayState(
videoQualityCount: Int,
audioVideoSyncEnabled: Boolean = false,
onlineSubtitleSearchAvailable: Boolean = false,
+ localSubtitleLoadingAvailable: Boolean = true,
showExternalPlayerAction: Boolean,
isCastConnected: Boolean
): VodOverlayState {
@@ -49,7 +50,8 @@ internal fun buildVodOverlayState(
nextChapterTargetMs = nextChapterTarget(visibleChapters, currentPositionMs),
showChapterAction = isVod && visibleChapters.isNotEmpty() && !isCastConnected,
showEpisodesAction = isVod && normalizedContentType == "SERIES_EPISODE" && showEpisodesAction,
- showSubtitleAction = isVod && (subtitleTrackCount > 0 || onlineSubtitleSearchAvailable),
+ showSubtitleAction = isVod &&
+ (subtitleTrackCount > 0 || onlineSubtitleSearchAvailable || localSubtitleLoadingAvailable),
showAudioAction = isVod && audioTrackCount > 0,
showVideoQualityAction = isVod && videoQualityCount > 0,
showAudioVideoSyncAction = isVod && audioVideoSyncEnabled && !isCastConnected,
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerChannelInfoOverlay.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerChannelInfoOverlay.kt
index 74ec0f39..de12128a 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerChannelInfoOverlay.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerChannelInfoOverlay.kt
@@ -97,6 +97,7 @@ fun ChannelInfoOverlay(
onOpenSplitScreen: () -> Unit = {},
subtitleTrackCount: Int = 0,
liveTranslationAvailable: Boolean = false,
+ localSubtitleLoadingAvailable: Boolean = true,
audioTrackCount: Int = 0,
videoQualityCount: Int = 0,
channelVariantCount: Int = 0,
@@ -434,7 +435,7 @@ fun ChannelInfoOverlay(
onInteraction = { handleMainActionFocus(null) }
)
}
- if (subtitleTrackCount > 0 || liveTranslationAvailable) {
+ if (subtitleTrackCount > 0 || liveTranslationAvailable || localSubtitleLoadingAvailable) {
item {
QuickActionButton(
icon = stringResource(R.string.player_subs),
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerControlsChrome.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerControlsChrome.kt
index c9af3f1d..f7bfbbac 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerControlsChrome.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerControlsChrome.kt
@@ -752,6 +752,7 @@ private fun PlayerLiveInfo(
aspectRatioLabel: String,
subtitleTrackCount: Int,
liveTranslationAvailable: Boolean,
+ localSubtitleLoadingAvailable: Boolean = true,
audioTrackCount: Int,
videoQualityCount: Int,
currentRecordingStatus: RecordingStatus?,
@@ -855,7 +856,7 @@ private fun PlayerLiveInfo(
}
val secondaryActions = buildList {
add(PlayerActionSpec("aspect_ratio", stringResource(R.string.player_aspect_ratio_label, aspectRatioLabel), onToggleAspectRatio))
- if (subtitleTrackCount > 0 || liveTranslationAvailable) {
+ if (subtitleTrackCount > 0 || liveTranslationAvailable || localSubtitleLoadingAvailable) {
add(PlayerActionSpec("subtitles", stringResource(R.string.player_subs), onOpenSubtitleTracks))
}
if (audioTrackCount > 0) {
@@ -1085,9 +1086,7 @@ private fun PlayerVodInfo(
stringResource(if (isMuted) R.string.player_unmute else R.string.player_mute),
onToggleMute
))
- if (subtitleTrackCount > 0) {
- add(PlayerActionSpec("subtitles", stringResource(R.string.player_subs), onOpenSubtitleTracks))
- }
+ add(PlayerActionSpec("subtitles", stringResource(R.string.player_subs), onOpenSubtitleTracks))
if (videoQualityCount > 0) {
add(PlayerActionSpec("video_quality", stringResource(R.string.player_video_quality), onOpenVideoTracks))
}
diff --git a/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerSystemOverlays.kt b/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerSystemOverlays.kt
index fc8e5f96..ebf7cddd 100644
--- a/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerSystemOverlays.kt
+++ b/feature/playback/src/main/java/com/streamvault/feature/playback/player/overlay/PlayerSystemOverlays.kt
@@ -88,6 +88,9 @@ import com.streamvault.player.PlayerTrack
import com.streamvault.player.TrackType
import com.streamvault.player.AUDIO_VIDEO_OFFSET_MAX_MS
import com.streamvault.player.AUDIO_VIDEO_OFFSET_MIN_MS
+import com.streamvault.player.SUBTITLE_OFFSET_MAX_MS
+import com.streamvault.player.SUBTITLE_OFFSET_MIN_MS
+import com.streamvault.player.SUBTITLE_OFFSET_STEP_MS
import java.util.Locale
import com.streamvault.core.ui.interaction.TvClickableSurface
import com.streamvault.core.ui.interaction.TvButton
@@ -259,12 +262,15 @@ fun PlayerTrackSelectionDialog(
liveTranslationAvailable: Boolean = false,
liveTranslationActive: Boolean = false,
onlineSubtitleSearchAvailable: Boolean = false,
+ subtitleOffsetMs: Int = 0,
onDismiss: () -> Unit,
onSelectAudio: (String) -> Unit,
onSelectVideo: (String) -> Unit,
onSelectSubtitle: (String?) -> Unit,
onSelectLiveTranslation: () -> Unit = {},
onSearchOnlineSubtitles: () -> Unit = {},
+ onOpenSubtitleOffset: () -> Unit = {},
+ onLoadLocalSubtitle: () -> Unit = {},
) {
if (trackType == null) return
@@ -374,6 +380,23 @@ fun PlayerTrackSelectionDialog(
}
}
+ if (trackType == TrackType.TEXT) {
+ item {
+ TrackSelectionItem(
+ name = stringResource(R.string.player_subtitle_delay_action, subtitleOffsetMs),
+ isSelected = false,
+ onClick = onOpenSubtitleOffset
+ )
+ }
+ item {
+ TrackSelectionItem(
+ name = stringResource(R.string.player_subtitle_load_from_device),
+ isSelected = false,
+ onClick = onLoadLocalSubtitle
+ )
+ }
+ }
+
if (trackType == TrackType.TEXT && onlineSubtitleSearchAvailable) {
item {
TrackSelectionItem(
@@ -911,6 +934,104 @@ fun PlayerAudioVideoOffsetDialog(
}
}
+@Composable
+fun PlayerSubtitleOffsetDialog(
+ visible: Boolean,
+ offsetMs: Int,
+ onDismiss: () -> Unit,
+ onAdjust: (Int) -> Unit,
+ onReset: () -> Unit
+) {
+ if (!visible) return
+
+ val firstItemFocusRequester = remember { FocusRequester() }
+ LaunchedEffect(visible) {
+ firstItemFocusRequester.requestFocusSafely(
+ tag = "PlayerSubtitleOffsetDialog",
+ target = "Earlier subtitle timing option"
+ )
+ }
+
+ Dialog(
+ onDismissRequest = onDismiss,
+ properties = DialogProperties(usePlatformDefaultWidth = false)
+ ) {
+ Box(
+ modifier = Modifier
+ .fillMaxSize()
+ .background(Color.Black.copy(alpha = 0.8f))
+ .clickable(onClick = onDismiss),
+ contentAlignment = Alignment.Center
+ ) {
+ Column(
+ modifier = Modifier
+ .widthIn(min = 340.dp, max = 460.dp)
+ .background(SurfaceElevated, RoundedCornerShape(12.dp))
+ .padding(24.dp)
+ .onPreviewKeyEvent { event ->
+ if (event.nativeKeyEvent.action != KeyEvent.ACTION_DOWN) return@onPreviewKeyEvent false
+ when (event.nativeKeyEvent.keyCode) {
+ KeyEvent.KEYCODE_DPAD_UP,
+ KeyEvent.KEYCODE_DPAD_DOWN,
+ KeyEvent.KEYCODE_DPAD_LEFT,
+ KeyEvent.KEYCODE_DPAD_RIGHT,
+ KeyEvent.KEYCODE_DPAD_CENTER,
+ KeyEvent.KEYCODE_ENTER,
+ KeyEvent.KEYCODE_NUMPAD_ENTER,
+ KeyEvent.KEYCODE_BACK -> false
+ else -> true
+ }
+ }
+ ) {
+ Text(
+ text = stringResource(R.string.player_subtitle_delay_title),
+ style = MaterialTheme.typography.titleLarge,
+ color = Color.White
+ )
+ Text(
+ text = stringResource(R.string.player_subtitle_delay_hint),
+ style = MaterialTheme.typography.bodySmall,
+ color = OnSurfaceDim,
+ modifier = Modifier.padding(top = 6.dp)
+ )
+ Text(
+ text = stringResource(R.string.player_subtitle_delay_current, offsetMs),
+ style = MaterialTheme.typography.bodyMedium,
+ color = Primary,
+ modifier = Modifier.padding(top = 12.dp, bottom = 16.dp)
+ )
+
+ LazyColumn(verticalArrangement = Arrangement.spacedBy(8.dp)) {
+ item {
+ TrackSelectionItem(
+ name = stringResource(R.string.player_subtitle_delay_earlier, SUBTITLE_OFFSET_STEP_MS),
+ isSelected = false,
+ onClick = { onAdjust(-SUBTITLE_OFFSET_STEP_MS) },
+ enabled = offsetMs > SUBTITLE_OFFSET_MIN_MS,
+ modifier = Modifier.focusRequester(firstItemFocusRequester)
+ )
+ }
+ item {
+ TrackSelectionItem(
+ name = stringResource(R.string.player_subtitle_delay_later, SUBTITLE_OFFSET_STEP_MS),
+ isSelected = false,
+ onClick = { onAdjust(SUBTITLE_OFFSET_STEP_MS) },
+ enabled = offsetMs < SUBTITLE_OFFSET_MAX_MS
+ )
+ }
+ item {
+ TrackSelectionItem(
+ name = stringResource(R.string.player_subtitle_delay_reset),
+ isSelected = offsetMs == 0,
+ onClick = onReset
+ )
+ }
+ }
+ }
+ }
+ }
+}
+
@Composable
fun PlayerEpisodeSelectionDialog(
visible: Boolean,
diff --git a/feature/playback/src/main/res/values/playback_player_strings.xml b/feature/playback/src/main/res/values/playback_player_strings.xml
index a3fd24eb..2abc3c49 100644
--- a/feature/playback/src/main/res/values/playback_player_strings.xml
+++ b/feature/playback/src/main/res/values/playback_player_strings.xml
@@ -1,10 +1,22 @@
<resources xmlns:tools="http://schemas.android.com/tools">
<string name="player_search_online_subtitles" tools:ignore="MissingTranslation">Search online subtitles</string>
+ <string name="player_subtitle_load_from_device" tools:ignore="MissingTranslation">Load SRT from device</string>
+ <string name="player_subtitle_delay_action" tools:ignore="MissingTranslation">Subtitle delay (%1$+d ms)</string>
+ <string name="player_subtitle_delay_title" tools:ignore="MissingTranslation">Subtitle delay</string>
+ <string name="player_subtitle_delay_hint" tools:ignore="MissingTranslation">Negative values show subtitles earlier; positive values show them later.</string>
+ <string name="player_subtitle_delay_current" tools:ignore="MissingTranslation">Current delay: %1$+d ms</string>
+ <string name="player_subtitle_delay_earlier" tools:ignore="MissingTranslation">Show subtitles %1$d ms earlier</string>
+ <string name="player_subtitle_delay_later" tools:ignore="MissingTranslation">Show subtitles %1$d ms later</string>
+ <string name="player_subtitle_delay_reset" tools:ignore="MissingTranslation">Reset delay</string>
+ <string name="player_subtitle_loaded" tools:ignore="MissingTranslation">%1$s loaded. The player is loading the subtitle.</string>
+ <string name="player_subtitle_invalid_file" tools:ignore="MissingTranslation">Choose a valid .srt subtitle file.</string>
+ <string name="player_subtitle_file_too_large" tools:ignore="MissingTranslation">Subtitle files must be 20 MB or smaller.</string>
+ <string name="player_subtitle_load_failed" tools:ignore="MissingTranslation">Could not load this subtitle file.</string>
<string name="player_subtitle_search_title" tools:ignore="MissingTranslation">Find subtitles</string>
<string name="player_subtitle_search_signed_in" tools:ignore="MissingTranslation">Choose a subtitle to add to this video.</string>
<string name="player_subtitle_search_results_for" tools:ignore="MissingTranslation">Results for %1$s</string>
- <string name="player_subtitle_search_signed_out" tools:ignore="MissingTranslation">Connect your OpenSubtitles account in Settings to search and download subtitles.</string>
- <string name="player_subtitle_search_open_settings" tools:ignore="MissingTranslation">Open Settings</string>
+ <string name="player_subtitle_search_signed_out" tools:ignore="MissingTranslation">You can search without signing in if anonymous access is enabled. Sign in to use your account’s download allowance.</string>
+ <string name="player_subtitle_search_open_settings" tools:ignore="MissingTranslation">Connect account (optional)</string>
<string name="player_subtitle_search_loading" tools:ignore="MissingTranslation">Searching OpenSubtitles…</string>
<string name="player_subtitle_search_no_results" tools:ignore="MissingTranslation">No subtitles found for this title and language.</string>
<string name="player_subtitle_search_retry" tools:ignore="MissingTranslation">Search again</string>
diff --git a/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerBackNavigationPolicyTest.kt b/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerBackNavigationPolicyTest.kt
index c85ce503..25b394ce 100644
--- a/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerBackNavigationPolicyTest.kt
+++ b/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerBackNavigationPolicyTest.kt
@@ -42,6 +42,12 @@ class PlayerBackNavigationPolicyTest {
assertThat(playerBackAction(state)).isEqualTo(PlayerBackAction.CLOSE_AUDIO_VIDEO_OFFSET_DIALOG)
}
+ @Test
+ fun `subtitle delay dialog closes before returning to playback`() {
+ assertThat(playerBackAction(PlayerBackNavigationState(showSubtitleOffsetDialog = true)))
+ .isEqualTo(PlayerBackAction.CLOSE_SUBTITLE_OFFSET_DIALOG)
+ }
+
@Test
fun `live overlays close before controls`() {
val state = PlayerBackNavigationState(
diff --git a/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerInputPolicyTest.kt b/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerInputPolicyTest.kt
index 61b41b8e..ccc18dde 100644
--- a/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerInputPolicyTest.kt
+++ b/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerInputPolicyTest.kt
@@ -76,6 +76,16 @@ class PlayerInputPolicyTest {
.isEqualTo(PlayerInputAction.Pass)
}
+ @Test
+ fun `subtitle offset Back dismisses the dialog and directional keys pass through`() {
+ val state = liveState(showSubtitleOffsetDialog = true)
+
+ assertThat(playerInputDecision(state, PlayerInputKey.Back).action)
+ .isEqualTo(PlayerInputAction.DismissSubtitleOffset)
+ assertThat(playerInputDecision(state, PlayerInputKey.DpadRight).action)
+ .isEqualTo(PlayerInputAction.Pass)
+ }
+
@Test
fun `speed modal consumes unrelated keys but passes navigation`() {
val state = liveState(showSpeedSelection = true)
@@ -256,6 +266,7 @@ class PlayerInputPolicyTest {
showVariantSelection: Boolean = false,
showSpeedSelection: Boolean = false,
showAudioVideoOffsetDialog: Boolean = false,
+ showSubtitleOffsetDialog: Boolean = false,
showStopPlaybackTimerDialog: Boolean = false,
showIdleStandbyTimerDialog: Boolean = false,
showProgramHistory: Boolean = false,
@@ -280,6 +291,7 @@ class PlayerInputPolicyTest {
showVariantSelection = showVariantSelection,
showSpeedSelection = showSpeedSelection,
showAudioVideoOffsetDialog = showAudioVideoOffsetDialog,
+ showSubtitleOffsetDialog = showSubtitleOffsetDialog,
showStopPlaybackTimerDialog = showStopPlaybackTimerDialog,
showIdleStandbyTimerDialog = showIdleStandbyTimerDialog,
showProgramHistory = showProgramHistory,
diff --git a/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerModalStateTest.kt b/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerModalStateTest.kt
index ce8f9774..debe647a 100644
--- a/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerModalStateTest.kt
+++ b/feature/playback/src/test/java/com/streamvault/feature/playback/player/PlayerModalStateTest.kt
@@ -48,6 +48,16 @@ class PlayerModalStateTest {
assertThat(state.hasVisibleModal).isTrue()
}
+ @Test
+ fun `subtitle delay modal is mutually exclusive with other player modals`() {
+ val state = PlayerModalState()
+ .open(PlayerModal.TrackSelection(TrackType.TEXT))
+ .open(PlayerModal.SubtitleOffset)
+
+ assertThat(state.trackSelection).isNull()
+ assertThat(state.showSubtitleOffsetDialog).isTrue()
+ }
+
@Test
fun `dismissing a modal clears the active modal`() {
val state = PlayerModalState()
diff --git a/feature/playback/src/test/java/com/streamvault/feature/playback/player/VodOverlayStateTest.kt b/feature/playback/src/test/java/com/streamvault/feature/playback/player/VodOverlayStateTest.kt
index 818b6327..30c2b96e 100644
--- a/feature/playback/src/test/java/com/streamvault/feature/playback/player/VodOverlayStateTest.kt
+++ b/feature/playback/src/test/java/com/streamvault/feature/playback/player/VodOverlayStateTest.kt
@@ -143,7 +143,7 @@ class VodOverlayStateTest {
}
@Test
- fun `negative capability counts are treated as unavailable`() {
+ fun `vod subtitle action remains available for local subtitle loading`() {
val state = buildVodOverlayState(
contentType = "MOVIE",
isCatchUpPlayback = false,
@@ -157,7 +157,7 @@ class VodOverlayStateTest {
isCastConnected = false
)
- assertThat(state.showSubtitleAction).isFalse()
+ assertThat(state.showSubtitleAction).isTrue()
assertThat(state.showAudioAction).isFalse()
assertThat(state.showVideoQualityAction).isFalse()
assertThat(state.showExternalPlayerAction).isTrue()
diff --git a/feature/settings/src/main/java/com/streamvault/feature/settings/presentation/OpenSubtitlesAccountSettings.kt b/feature/settings/src/main/java/com/streamvault/feature/settings/presentation/OpenSubtitlesAccountSettings.kt
index a607747f..09d8fa1d 100644
--- a/feature/settings/src/main/java/com/streamvault/feature/settings/presentation/OpenSubtitlesAccountSettings.kt
+++ b/feature/settings/src/main/java/com/streamvault/feature/settings/presentation/OpenSubtitlesAccountSettings.kt
@@ -96,7 +96,7 @@ internal fun OpenSubtitlesAccountSettings(
if (showSignIn) {
var username by rememberSaveable { mutableStateOf("") }
- var password by rememberSaveable { mutableStateOf("") }
+ var password by remember { mutableStateOf("") }
LaunchedEffect(account) {
if (account != null) showSignIn = false
}
diff --git a/feature/settings/src/main/res/values/strings.xml b/feature/settings/src/main/res/values/strings.xml
index 6c11aace..a013f7bc 100644
--- a/feature/settings/src/main/res/values/strings.xml
+++ b/feature/settings/src/main/res/values/strings.xml
@@ -725,11 +725,11 @@
<string name="settings_drive_manage_title">Saved Drive backups</string>
<string name="settings_providers_subtitle">Switch, sync, edit, and troubleshoot your IPTV sources.</string>
<string name="settings_opensubtitles_title">OpenSubtitles</string>
- <string name="settings_opensubtitles_description">Use your OpenSubtitles account to find subtitles while watching movies and series. Downloads count toward your account’s daily allowance.</string>
- <string name="settings_opensubtitles_connect">Connect OpenSubtitles account</string>
+ <string name="settings_opensubtitles_description">Anonymous access depends on this app’s OpenSubtitles settings. Sign in optionally to use your account-specific download allowance.</string>
+ <string name="settings_opensubtitles_connect">Connect account (optional)</string>
<string name="settings_opensubtitles_signed_out">Not connected</string>
<string name="settings_opensubtitles_sign_in_title">Connect OpenSubtitles</string>
- <string name="settings_opensubtitles_sign_in_subtitle">Sign in with your OpenSubtitles.com account. Your password is stored encrypted on this device.</string>
+ <string name="settings_opensubtitles_sign_in_subtitle">Sign in optionally to use your OpenSubtitles account. Your password is stored encrypted on this device.</string>
<string name="settings_opensubtitles_username">Username</string>
<string name="settings_opensubtitles_password">Password</string>
<string name="settings_opensubtitles_sign_in">Sign in</string>
diff --git a/player/src/main/java/com/streamvault/player/ExternalSubtitlePlayback.kt b/player/src/main/java/com/streamvault/player/ExternalSubtitlePlayback.kt
index c3283cad..71207782 100644
--- a/player/src/main/java/com/streamvault/player/ExternalSubtitlePlayback.kt
+++ b/player/src/main/java/com/streamvault/player/ExternalSubtitlePlayback.kt
@@ -37,10 +37,12 @@ internal fun TrackSelectionParameters.withExternalSubtitleEnabled(): TrackSelect
internal fun buildExternalSubtitleConfiguration(
subtitleUri: Uri,
- language: String
+ language: String,
+ label: String? = null
): MediaItem.SubtitleConfiguration = MediaItem.SubtitleConfiguration.Builder(subtitleUri)
.setMimeType(MimeTypes.APPLICATION_SUBRIP)
.setLanguage(language)
+ .setLabel(label)
.setSelectionFlags(C.SELECTION_FLAG_DEFAULT)
.build()
diff --git a/player/src/main/java/com/streamvault/player/Media3PlayerEngine.kt b/player/src/main/java/com/streamvault/player/Media3PlayerEngine.kt
index d5d0244f..aff5b2fd 100644
--- a/player/src/main/java/com/streamvault/player/Media3PlayerEngine.kt
+++ b/player/src/main/java/com/streamvault/player/Media3PlayerEngine.kt
@@ -283,6 +283,9 @@ class Media3PlayerEngine @Inject constructor(
private val audioVideoOffsetUs = AtomicLong(0L)
private val _audioVideoOffsetMs = MutableStateFlow(0)
override val audioVideoOffsetMs: StateFlow<Int> = _audioVideoOffsetMs.asStateFlow()
+ private val subtitleOffsetUs = AtomicLong(0L)
+ private val _subtitleOffsetMs = MutableStateFlow(0)
+ override val subtitleOffsetMs: StateFlow<Int> = _subtitleOffsetMs.asStateFlow()
private val _audioVideoSyncEnabled = MutableStateFlow(false)
override val audioVideoSyncEnabled: StateFlow<Boolean> = _audioVideoSyncEnabled.asStateFlow()
@@ -517,6 +520,10 @@ class Media3PlayerEngine @Inject constructor(
override fun prepare(streamInfo: StreamInfo) {
if (ensureNotDisposed("prepare")) return
+ if (_subtitleOffsetMs.value != 0) {
+ _subtitleOffsetMs.value = 0
+ subtitleOffsetUs.set(0L)
+ }
if (!vodTrackPreferencesConfiguredForNextPrepare) {
trackController.setVodTrackPreferences(exoPlayer, null)
}
@@ -524,6 +531,12 @@ class Media3PlayerEngine @Inject constructor(
prepareInternal(streamInfo = streamInfo, preserveRetryState = false, seekPositionMs = null, autoPlay = true)
}
+ private fun withSubtitleOffset(
+ mediaSource: androidx.media3.exoplayer.source.MediaSource
+ ): androidx.media3.exoplayer.source.MediaSource = SubtitleOffsetMediaSource(mediaSource) {
+ subtitleOffsetUs.get()
+ }
+
override fun renewStreamUrl(streamInfo: StreamInfo) {
if (ensureNotDisposed("renewStreamUrl")) return
val player = exoPlayer ?: return
@@ -558,7 +571,7 @@ class Media3PlayerEngine @Inject constructor(
preload = false
).second
- player.setMediaSource(mediaSource, /* resetPosition= */ false)
+ player.setMediaSource(withSubtitleOffset(mediaSource), /* resetPosition= */ false)
player.prepare()
Log.i(
@@ -750,6 +763,14 @@ class Media3PlayerEngine @Inject constructor(
audioVideoOffsetUs.set(effectiveOffset * 1_000L)
}
+ override fun setSubtitleOffsetMs(offsetMs: Int) {
+ val clamped = offsetMs.coerceIn(SUBTITLE_OFFSET_MIN_MS, SUBTITLE_OFFSET_MAX_MS)
+ if (_subtitleOffsetMs.value == clamped) return
+ _subtitleOffsetMs.value = clamped
+ subtitleOffsetUs.set(clamped * 1_000L)
+ exoPlayer?.let { player -> player.seekTo(player.currentPosition) }
+ }
+
override fun setAudioOutputPreference(preference: AudioOutputPreference) {
if (audioOutputPreference == preference) return
audioOutputPreference = preference
@@ -885,7 +906,7 @@ class Media3PlayerEngine @Inject constructor(
liveAudioTap = tap
}
- override fun addExternalSubtitle(subtitleUri: android.net.Uri, language: String) {
+ override fun addExternalSubtitle(subtitleUri: android.net.Uri, language: String, label: String?) {
val player = exoPlayer ?: return
val streamInfo = lastStreamInfo ?: return
val retryPolicy = currentRetryPolicy ?: return
@@ -901,7 +922,7 @@ class Media3PlayerEngine @Inject constructor(
vodHttpProtocolMode = requestedVodHttpProtocolMode,
preload = false
)
- val subtitleConfig = buildExternalSubtitleConfiguration(subtitleUri, language)
+ val subtitleConfig = buildExternalSubtitleConfiguration(subtitleUri, language, label)
val subtitleSource = buildExternalSubtitleMediaSource(
dataSourceFactory = androidx.media3.datasource.DefaultDataSource.Factory(context),
configuration = subtitleConfig
@@ -909,7 +930,7 @@ class Media3PlayerEngine @Inject constructor(
val merged = androidx.media3.exoplayer.source.MergingMediaSource(mainMediaSource, subtitleSource)
player.trackSelectionParameters = player.trackSelectionParameters.withExternalSubtitleEnabled()
- player.setMediaSource(merged, /* resetPosition= */ false)
+ player.setMediaSource(withSubtitleOffset(merged), /* resetPosition= */ false)
player.prepare()
transition.resumePositionMs.takeIf { it > 0L }?.let(player::seekTo)
player.playWhenReady = transition.playWhenReady
@@ -1255,7 +1276,7 @@ class Media3PlayerEngine @Inject constructor(
if (managedSource != null) {
Log.i(TAG, "preload-source reused mediaId=$mediaId source=window")
}
- player.setMediaSource(mediaSource)
+ player.setMediaSource(withSubtitleOffset(mediaSource))
player.prepare()
seekPositionMs?.takeIf { it > 0L }?.let(player::seekTo)
diff --git a/player/src/main/java/com/streamvault/player/PlayerEngine.kt b/player/src/main/java/com/streamvault/player/PlayerEngine.kt
index b1ff6a2e..0800523b 100644
--- a/player/src/main/java/com/streamvault/player/PlayerEngine.kt
+++ b/player/src/main/java/com/streamvault/player/PlayerEngine.kt
@@ -26,6 +26,9 @@ import kotlinx.coroutines.flow.StateFlow
const val AUDIO_VIDEO_OFFSET_MIN_MS = -2_000
const val AUDIO_VIDEO_OFFSET_MAX_MS = 2_000
const val AUDIO_VIDEO_OFFSET_STEP_MS = 50
+const val SUBTITLE_OFFSET_MIN_MS = -5_000
+const val SUBTITLE_OFFSET_MAX_MS = 5_000
+const val SUBTITLE_OFFSET_STEP_MS = 100
const val PLAYER_TRACK_AUTO_ID = "__auto__"
@@ -57,6 +60,7 @@ interface PlayerEngine {
val playbackSpeed: StateFlow<Float>
val audioVideoOffsetMs: StateFlow<Int>
val audioVideoSyncEnabled: StateFlow<Boolean>
+ val subtitleOffsetMs: StateFlow<Int>
val timeshiftState: StateFlow<LiveTimeshiftState>
val renderSurfaceType: StateFlow<PlayerRenderSurfaceType>
@@ -86,6 +90,7 @@ interface PlayerEngine {
fun setPlaybackSpeed(speed: Float)
fun setAudioVideoSyncEnabled(enabled: Boolean)
fun setAudioVideoOffsetMs(offsetMs: Int)
+ fun setSubtitleOffsetMs(offsetMs: Int)
fun setAudioOutputPreference(preference: AudioOutputPreference)
fun setCompatibilityMemoryEnabled(enabled: Boolean)
fun clearLearnedPlaybackCompatibility()
@@ -101,7 +106,7 @@ interface PlayerEngine {
fun selectAudioTrack(trackId: String)
fun selectVideoTrack(trackId: String)
fun selectSubtitleTrack(trackId: String?) // null to disable subtitles
- fun addExternalSubtitle(subtitleUri: android.net.Uri, language: String)
+ fun addExternalSubtitle(subtitleUri: android.net.Uri, language: String, label: String? = null)
fun setInjectedSubtitleText(text: String?)
fun setLiveAudioTap(tap: LiveAudioTap?)
fun clearLiveAudioTap() = setLiveAudioTap(null)
diff --git a/player/src/main/java/com/streamvault/player/SubtitleOffsetMediaSource.kt b/player/src/main/java/com/streamvault/player/SubtitleOffsetMediaSource.kt
new file mode 100644
index 00000000..c5c631ed
--- /dev/null
+++ b/player/src/main/java/com/streamvault/player/SubtitleOffsetMediaSource.kt
@@ -0,0 +1,110 @@
+package com.streamvault.player
+
+import androidx.media3.common.C
+import androidx.media3.common.MimeTypes
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.decoder.DecoderInputBuffer
+import androidx.media3.exoplayer.source.MediaPeriod
+import androidx.media3.exoplayer.source.MediaSource
+import androidx.media3.exoplayer.source.SampleStream
+import androidx.media3.exoplayer.source.WrappingMediaSource
+import androidx.media3.exoplayer.trackselection.ExoTrackSelection
+import androidx.media3.exoplayer.upstream.Allocator
+import androidx.media3.exoplayer.FormatHolder
+
+/** Shifts text sample timestamps while leaving audio and video timing unchanged. */
+@UnstableApi
+internal class SubtitleOffsetMediaSource(
+ mediaSource: MediaSource,
+ private val offsetUs: () -> Long
+) : WrappingMediaSource(mediaSource) {
+ override fun createPeriod(
+ id: MediaSource.MediaPeriodId,
+ allocator: Allocator,
+ startPositionUs: Long
+ ): MediaPeriod = SubtitleOffsetMediaPeriod(
+ delegate = super.createPeriod(id, allocator, startPositionUs),
+ offsetUs = offsetUs
+ )
+
+ override fun releasePeriod(mediaPeriod: MediaPeriod) {
+ val wrapped = mediaPeriod as? SubtitleOffsetMediaPeriod
+ ?: error("Unexpected media period released by subtitle-offset source")
+ super.releasePeriod(wrapped.delegate)
+ }
+}
+
+@UnstableApi
+internal class SubtitleOffsetMediaPeriod(
+ internal val delegate: MediaPeriod,
+ private val offsetUs: () -> Long
+) : MediaPeriod by delegate {
+ override fun prepare(callback: MediaPeriod.Callback, positionUs: Long) {
+ delegate.prepare(
+ object : MediaPeriod.Callback {
+ override fun onPrepared(mediaPeriod: MediaPeriod) {
+ callback.onPrepared(this@SubtitleOffsetMediaPeriod)
+ }
+
+ override fun onContinueLoadingRequested(source: MediaPeriod) {
+ callback.onContinueLoadingRequested(this@SubtitleOffsetMediaPeriod)
+ }
+ },
+ positionUs
+ )
+ }
+
+ override fun selectTracks(
+ selections: Array<out ExoTrackSelection?>,
+ mayRetainStreamFlags: BooleanArray,
+ streams: Array<out SampleStream?>,
+ streamResetFlags: BooleanArray,
+ positionUs: Long
+ ): Long {
+ val existingWrappers = Array<SubtitleOffsetSampleStream?>(streams.size) { index ->
+ streams[index] as? SubtitleOffsetSampleStream
+ }
+ val childStreams = Array<SampleStream?>(streams.size) { index ->
+ existingWrappers[index]?.delegate ?: streams[index]
+ }
+ val selectedPositionUs = delegate.selectTracks(
+ selections,
+ mayRetainStreamFlags,
+ childStreams,
+ streamResetFlags,
+ positionUs
+ )
+
+ @Suppress("UNCHECKED_CAST")
+ val mutableStreams = streams as Array<SampleStream?>
+ for (index in mutableStreams.indices) {
+ val selection = selections[index]
+ val sampleMimeType = selection?.selectedFormat?.sampleMimeType
+ mutableStreams[index] = childStreams[index]?.let { childStream ->
+ if (sampleMimeType != null && MimeTypes.getTrackType(sampleMimeType) == C.TRACK_TYPE_TEXT) {
+ existingWrappers[index]?.takeIf { it.delegate === childStream }
+ ?: SubtitleOffsetSampleStream(childStream, offsetUs)
+ } else {
+ childStream
+ }
+ }
+ }
+ return selectedPositionUs
+ }
+}
+
+@UnstableApi
+internal class SubtitleOffsetSampleStream(
+ internal val delegate: SampleStream,
+ private val offsetUs: () -> Long
+) : SampleStream by delegate {
+ override fun readData(formatHolder: FormatHolder, buffer: DecoderInputBuffer, readFlags: Int): Int {
+ val result = delegate.readData(formatHolder, buffer, readFlags)
+ if (result == C.RESULT_BUFFER_READ && !buffer.isEndOfStream) {
+ buffer.timeUs += offsetUs()
+ }
+ return result
+ }
+
+ override fun skipData(positionUs: Long): Int = delegate.skipData(positionUs - offsetUs())
+}
diff --git a/player/src/test/java/com/streamvault/player/ExternalSubtitlePlaybackTest.kt b/player/src/test/java/com/streamvault/player/ExternalSubtitlePlaybackTest.kt
index 54879a4d..2eddaa12 100644
--- a/player/src/test/java/com/streamvault/player/ExternalSubtitlePlaybackTest.kt
+++ b/player/src/test/java/com/streamvault/player/ExternalSubtitlePlaybackTest.kt
@@ -42,15 +42,17 @@ class ExternalSubtitlePlaybackTest {
}
@Test
- fun `external subtitle configuration preserves language and uses subrip`() {
+ fun `external subtitle configuration preserves language label and uses subrip`() {
val configuration = buildExternalSubtitleConfiguration(
subtitleUri = Uri.parse("https://example.test/subtitles/episode.srt"),
- language = "he"
+ language = "he",
+ label = "episode.srt"
)
assertThat(configuration.uri.toString()).isEqualTo("https://example.test/subtitles/episode.srt")
assertThat(configuration.mimeType).isEqualTo(MimeTypes.APPLICATION_SUBRIP)
assertThat(configuration.language).isEqualTo("he")
+ assertThat(configuration.label).isEqualTo("episode.srt")
assertThat(configuration.selectionFlags).isEqualTo(C.SELECTION_FLAG_DEFAULT)
}
diff --git a/player/src/test/java/com/streamvault/player/SubtitleOffsetMediaSourceTest.kt b/player/src/test/java/com/streamvault/player/SubtitleOffsetMediaSourceTest.kt
new file mode 100644
index 00000000..05eaf72d
--- /dev/null
+++ b/player/src/test/java/com/streamvault/player/SubtitleOffsetMediaSourceTest.kt
@@ -0,0 +1,71 @@
+package com.streamvault.player
+
+import androidx.media3.common.C
+import androidx.media3.decoder.DecoderInputBuffer
+import androidx.media3.exoplayer.FormatHolder
+import androidx.media3.exoplayer.source.SampleStream
+import com.google.common.truth.Truth.assertThat
+import org.junit.Test
+
+class SubtitleOffsetMediaSourceTest {
+
+ @Test
+ fun `sample timestamps shift both earlier and later as the offset changes`() {
+ val delegate = TestSampleStream(sampleTimeUs = 2_000_000L)
+ var offsetUs = 300_000L
+ val stream = SubtitleOffsetSampleStream(delegate) { offsetUs }
+ val holder = FormatHolder()
+ val buffer = DecoderInputBuffer(DecoderInputBuffer.BUFFER_REPLACEMENT_MODE_NORMAL)
+
+ assertThat(stream.readData(holder, buffer, 0)).isEqualTo(C.RESULT_BUFFER_READ)
+ assertThat(buffer.timeUs).isEqualTo(2_300_000L)
+
+ offsetUs = -450_000L
+ assertThat(stream.readData(holder, buffer, 0)).isEqualTo(C.RESULT_BUFFER_READ)
+ assertThat(buffer.timeUs).isEqualTo(1_550_000L)
+ }
+
+ @Test
+ fun `skip position compensates for the subtitle timestamp offset`() {
+ val delegate = TestSampleStream(sampleTimeUs = 0L)
+ val stream = SubtitleOffsetSampleStream(delegate) { -250_000L }
+
+ stream.skipData(positionUs = 1_000_000L)
+
+ assertThat(delegate.lastSkipPositionUs).isEqualTo(1_250_000L)
+ }
+
+ @Test
+ fun `end of stream marker is not shifted`() {
+ val delegate = TestSampleStream(sampleTimeUs = 0L, endOfStream = true)
+ val stream = SubtitleOffsetSampleStream(delegate) { 500_000L }
+ val buffer = DecoderInputBuffer(DecoderInputBuffer.BUFFER_REPLACEMENT_MODE_NORMAL)
+
+ assertThat(stream.readData(FormatHolder(), buffer, 0)).isEqualTo(C.RESULT_BUFFER_READ)
+ assertThat(buffer.isEndOfStream).isTrue()
+ assertThat(buffer.timeUs).isEqualTo(0L)
+ }
+
+ private class TestSampleStream(
+ private val sampleTimeUs: Long,
+ private val endOfStream: Boolean = false
+ ) : SampleStream {
+ var lastSkipPositionUs: Long? = null
+ private set
+
+ override fun isReady(): Boolean = true
+
+ override fun maybeThrowError() = Unit
+
+ override fun readData(formatHolder: FormatHolder, buffer: DecoderInputBuffer, readFlags: Int): Int {
+ buffer.timeUs = sampleTimeUs
+ if (endOfStream) buffer.addFlag(C.BUFFER_FLAG_END_OF_STREAM)
+ return C.RESULT_BUFFER_READ
+ }
+
+ override fun skipData(positionUs: Long): Int {
+ lastSkipPositionUs = positionUs
+ return 1
+ }
+ }
+}