[Feat]: Change back to 3 Mutex locks in EncodingPipelineOutput.kt‎

[dimadesu]

Version

3.0.1-SNAPSHOT

Environment that reproduces the issue

I test mostly on Samsung S20 FE

Use case description

I've updated LifeStreamer app to latest version and noticed I started getting issue with app getting stuck on start stream in "Connecting" state.

I couldn't find what is causing it, so I had to update StreamPack commit by commit to see when issue appears.

I've found it was this commit e899a31

Looks like it is combining 3 locks into one.

I've tried many things on my app side to fix it, but nothing could fix. I tried reverting back to 3 locks in StreamPack - it works fine.

Not sure if anyone else had issues with this, but I'm thinking maybe it's best to change it back to 3 locks. What do you think @ThibaultBee?

Git issue in my repo for the reference dimadesu/LifeStreamer#129

Proposed solution

Something like this dimadesu@8263450

Alternative solutions

No response

[ThibaultBee]

Is there a way to reproduce this in the demo or a standalone application or a code snippet?
Are you using a custom endpoint?
Is your deadlock happening on startStream(url)?

[dimadesu]

Hey @ThibaultBee thanks for quick reply!

This could be a bit specific to my app as I have foreground service. Sometimes only UI or only service gets killed it can get into states like that.

The way I reproduce I start stream, then I install app with Android Studio mid-stream and if I start stream it can never connect.

I think something locks UI thread. Then it can never connect until I kill UI by swiping away.

I'm testing some more, maybe reverting locks didn't fully fix it. I'll try to revert more from this commit and test.
It's very late here I'll report back tomorrow.

[ThibaultBee]

Have you called release in the meantime?
I guess you are using SRT.
It might be related to the service. Could you provide a minimalist test application so I can reproduce on my side?

[dimadesu]

Oh actually don't worry about it. I finally found a fix on my app side. I used all of my best AI - it couldn't figure it out. This was a strange issue.

Somehow stopping preview before reconnection attempt helped to clear some bad state or smth.

I just couldn't find the problem or fix for 2 days, so I was a bit desperate and then I found that issue starts with this commit, so I suspected smth wrong with it.

Now I switched to 3.0.1-SNAPSHOT and it's fine. 🤷‍♂️ So I guess it's okay to close this issue. Sorry to disturb you! 🙇

[dimadesu]

I ran it through Claude Sonnet 4.5 AI and asked why camera session gets into weird state and needs the fix. Here is what it said you want to know.

Camera Session Race Condition During Reconnection

Problem Summary

During stream reconnection, the camera session can get into a weird state where startStream() fails with:

Target type must be in the current capture session: stream

This document explains the root cause and why stopping preview during reconnection fixes it.

The Root Cause

The camera output list is not synchronized with encoder resets.

During reconnection:

• Encoder resets create new surfaces
• But camera.setOutput(newSurface) is never called
• The camera's output map still has: {"stream": oldDestroyedSurface}
• When startStream() tries to add the target, it finds the output but the surface is invalid/stale

Detailed Timeline

Initial State (Before Reconnection)

Camera Session Outputs: [preview, stream]
Camera Session Targets: [preview, stream]  ✓ Both active

What Happens During Reconnection (WITHOUT the fix)

1. ViewModel calls stopStream()

camera.stopStream() → controller.removeTarget(STREAM_NAME)

• Camera Session Outputs: [preview, stream] ← stream OUTPUT still there
• Camera Session Targets: [preview] ← stream TARGET removed
• Result: Preview still running, stream target inactive

Key Point: stopStream() only removes the TARGET (from capture requests), not the OUTPUT (surface from session).

2. Encoder resets in stopStreamImpl()

resetVideoEncoder() → _surfaceFlow.emit(null) → videoEncoder.reset()

• Surface flow emits null
• Pipeline collector sees surface changed from oldSurface → null
• Calls input.removeOutputSurface(oldSurface) → only removes from processor
• Camera still has stream OUTPUT registered with old surface!

3. Encoder creates NEW surface

videoEncoder.reset() → creates new MediaCodec surface → emits to surfaceFlow

• Surface flow emits newSurface
• Pipeline collector runs asynchronously in a separate coroutine
• The new surface is added to the processor but NOT to the camera

4. RACE CONDITION: Two async operations compete

Path A (Async): Pipeline collector

input.addOutputSurface(newSurface) 
  → processor.addOutputSurface(newSurface)
  → // Only adds to processor, NOT to camera!

Path B (Main reconnection thread): ViewModel reconnects

startStreamInternal() 
  → onStartStream() 
  → camera.startStream() 
  → controller.addTarget(STREAM_NAME) 
  → ERROR! "Target must be in session"

Why Does addTarget Fail?

The camera controller checks:

fun addTarget(name: String) {
    require(outputs.containsKey(name)) { 
        "Target type must be in the current capture session: $name" 
    }
    captureRequestBuilder.addTarget(outputs[name])
}

The problem:

1. The check passes because outputs["stream"] exists
2. BUT it points to the old destroyed surface from before the encoder reset
3. The new encoder surface hasn't been added to camera outputs
4. Camera session has: outputs = {preview: validSurface, stream: destroyedSurface}

Why Does camera.setOutput() Not Get Called?

Looking at the code flow:

• camera.setOutput(surface) is called during initial setup in VideoInput.addSourceSurface()
• This happens when the video source is first configured
• During encoder reset:
  • New surface is created by the encoder
  • Surface flows through: encoder → surfaceFlow → pipeline collector → processor
  • But camera.setOutput() is never called because that's only for SOURCE surfaces (camera input)
  • The stream surface is an OUTPUT surface (encoder input)

The architecture is:

Camera → [processor input surface] → Processor → [encoder output surfaces] → Encoders

• Camera's "stream" output should be the processor's INPUT surface (never changes)
• But somehow the camera controller has a "stream" output that points to the encoder surface directly
• This suggests a mismatch in how surfaces are managed

Why Preview Still Works

• Preview surface never changes (same TextureView/SurfaceView)
• Preview output stays valid in camera session
• Camera session state: outputs = {preview: validSurface, stream: destroyedSurface}
• Preview target can be activated/deactivated without issues

The Fix

What We Do

During reconnection cleanup in PreviewViewModel.handleDisconnection():

val videoSource = currentStreamer.videoInput?.sourceFlow?.value
if (videoSource is ICameraSource) {
    if (videoSource.isPreviewingFlow.value) {
        Log.d(TAG, "Stopping camera preview to reset camera session state...")
        videoSource.stopPreview()
        kotlinx.coroutines.delay(100) // Brief delay to ensure preview stops
        Log.d(TAG, "Camera preview stopped - will restart after reconnection")
    }
}

Why This Works

When you stop preview during reconnection:

videoSource.stopPreview()
  → controller.removeTarget(PREVIEW_NAME)
  → // Preview target removed

This triggers a session recreation when preview restarts later because:

1. Preview stops → camera session simplified to just inactive targets
2. During reconnection, encoders are recreated
3. When preview restarts (automatically through PreviewView), it creates a fresh camera session
4. The stale stream output reference gets cleared
5. Fresh session initialization properly sets up all outputs

The key is that stopping preview forces the camera to fully re-initialize, clearing stale output references, rather than keeping the camera session partially alive with only preview active.

Why Alternative Approaches Work

Why Killing UI Works

When you kill the UI:

• Entire preview is destroyed and recreated
• Camera session completely torn down
• All outputs cleared
• Fresh start with no stale references

Why Stopping and Restarting Fixes It

Same principle - forces full camera reinitialization instead of trying to reuse a partially-active session with stale references.

Location of Fix

The fix is in PreviewViewModel.handleDisconnection() at the point where we clean up before reconnection:

• File: app/src/main/java/com/dimadesu/lifestreamer/ui/main/PreviewViewModel.kt
• Lines: ~1459-1476 (in handleDisconnection() method)

This is the correct location because:

1. All reconnection flows through this method
2. Service notification failures delegate to this method
3. Manual reconnection attempts use this cleanup path
4. It happens before close() and before the reconnection attempt

Alternative Solutions Considered

1. Wait for surface to be added (doesn't work)

Adding delays or waiting for surfaceFlow.value != null doesn't help because:

• The surface IS created and emitted
• The problem is the camera's output map isn't updated with the new surface
• The race is between surface flow collection and startStream(), but even if we win the race, the camera output is still stale

2. Fix in StreamPack (proper solution)

The correct fix would be in StreamPack itself:

• Ensure encoder surface resets trigger camera output updates
• Or ensure outputs are validated/refreshed before startStream()
• Or separate the concept of preview/stream outputs more clearly

However, this would require changes to the StreamPack library architecture.

3. App-level workaround (current solution)

Stopping preview during reconnection is an effective workaround that:

• Works at the application level
• Doesn't require library changes
• Forces a clean camera session reset
• Is simple and maintainable

Lessons Learned

1. Preview keeping camera partially alive can cause state issues - During reconnection, preview should be stopped to ensure clean camera reinitialization.

2. Surface lifecycles are complex - Encoder surface resets don't automatically propagate to all components that reference them.

3. Async surface flow collection creates race conditions - The surface flow collector runs asynchronously, so by the time it processes new surfaces, other operations may have already tried to use stale references.

4. Camera output map can get stale - The camera controller's output map is not automatically synchronized with encoder surface lifecycles.

5. Stopping/restarting is sometimes safer than trying to maintain state - Clean reinitialization can be more reliable than trying to coordinate complex async state updates.

[dimadesu]

I think it's all good from StreamPack side. Can't reproduce the issue anymore after restarting the phone 🤷‍♂️ Tested on one more phone - looks good. Closing.

[ThibaultBee]

Hi,
There is indeed a race condition somewhere in the camera source (I suppose).
I need to investigate that.

Anyway, the exception could be try/catch when calling streamStream. If not, you should try/catch startStream in your service to show error to the user (or at least to the logcat).

[dimadesu]

@ThibaultBee okay I have THE FIX! Really simple.
Smth was still blocking the thread sometimes around making connection and I had another user that had this issue.
I tried and looked into many things, but I think the fix is simple in the end: add timeout on lock and maybe throw error or smth like that.
At least with timeout it unblocks the thread.
This fixed finally:
dimadesu@b635723

[ThibaultBee]

Hi,
Ok, I understand the fix. But it looks like a workaround. What would be the reason that connect never returns?
Also, I am working on a new RTMP provider. I don't want to spend lot of times working on this future legacy code.

Does the lock happens because of connectStream or connect?

[ThibaultBee]

Also, I don't this your workaround work.
The RTMP connect and connectStream are not cancellable as it. And coroutines needs the executing task to be cancellable.

[dimadesu]

No worries @ThibaultBee I'm just letting you know, that there's a chance of something getting stuck around this area.

It's up to you if you want to do anything about it or not. Now you're aware of it and can take it into consideration.

I'm not an expert in this area of programming, so when I have a complicated issue I run different AI models to see if AI can help me find where the issue comes from and suggest ideas how to fix it.

I couldn't figure it out with AI for days, but I knew it was something about locks not being released.

When I commented out the locking in the lock helper function the stuck issue was gone, but sometimes it was possible to start stream without video or audio source that was unplayable.

I'm testing mostly with SRT, so RTMP code changes I'm not too sure about.
AI did these changes and they looked reasonable, so I kept them for now. I can test more and see if I can make a diff smaller - maybe some of the changes are not required.

So no pressure for you to fix anything. These changes fix the issue for LifeStreamer app users at the moment at least for SRT. I can keep them in my fork, so that's fine.

[ThibaultBee]

Mutexes have changed lately. Could you try to reproduce with 3.1.0?