MediaMTX의 LL-HLS 조각 수를 6으로 설정하자 서버는 정상 기동했습니다. 문제는 방송 송출이 들어온 뒤에 나타났습니다. HLS 먹서가 생성에 실패하고 10초마다 다시 시도해, 40초 관측에 같은 실패가 5회 남았습니다. 조각 수가 바뀌지 않는데 재시도만 반복하는 상황이었습니다.
저는 이 오류를 송출 재시도로 다루는 대신, 잘못된 조각 수로 서버가 실행을 시작하지 않게 하는 방향을 택했습니다. PokeClip의 수신·녹화에 쓰던 MediaMTX를 조사하고 PR #6154에서 하위 라이브러리의 실행 조건을 공통 설정 검증으로 옮겼습니다. 수정 방향과 검증 범위는 제가 확정하고 코드 변경·실측·리뷰는 AI와 협업했습니다. PR은 2026년 8월 30일 병합됐으며 v1.21.0 정식 릴리스에 포함됐습니다.
두 계층이 다른 값을 허용했다
HLS는 짧은 미디어 조각과 그 목록을 제공하는 재생 방식입니다. MediaMTX는 설정을 받아 실제 HLS 생성을 하위 라이브러리에 맡기는데, 두 계층이 허용하는 조각 수가 달랐습니다. 당시 gohlslib v2.4.3의 먹서 코드는 lowLatency에 최소 7개, 다른 변형에 최소 3개를 요구했습니다. MediaMTX 설정 검증에는 같은 하한이 없었습니다.
hlsAlwaysRemux를 켜면 송출이 들어올 때 먹서를 자동으로 만듭니다. 앞서 본 40초의 반복 실패는 이 조건에서 나타났습니다. 자동 모드가 아니라면 재생을 시도할 때 만들어지는 먹서가 실패할 수 있습니다. 어느 쪽이든 서버 프로세스가 살아 있는 것과 HLS를 생성할 수 있는 것은 별개였습니다. 운영자가 서버의 정상 기동만 확인하면 실제 재생 요청까지 구성 오류를 발견하지 못할 수 있었습니다.
재시도보다 설정을 받아들이는 경계를 고쳤다
제가 재시도 쪽을 고치지 않은 이유는 실패 조건이 일시적이지 않았기 때문입니다. 네트워크가 회복되기를 기다리는 상황과 달리, 최소 7개를 요구하는 먹서에 6개를 계속 주면 다음 시도도 실패합니다. 필요한 최소값을 이미 알고 있으므로 설정을 받아들이는 시점에 사용자에게 돌려주는 편이 맞다고 판단했습니다.
변경은 Conf.Validate()의 HLS 검증 부분에 variant별 하한을 추가하는 방식입니다. 파일, 환경변수, API 설정 입력이 같은 검증을 거치므로 특정 입력 경로만 늦게 실패하는 문제를 남기지 않을 수 있습니다. 오류에는 잘못된 필드와 필요한 최소값을 표시했습니다.
| HLS 설정 | 거부할 값 | 허용할 경계값 |
|---|---|---|
lowLatency |
6 | 7 |
fmp4 |
2 | 3 |
mpegts |
2 | 3 |
| HLS 비활성화 | 이 하한 검사 미적용 | 관련 없는 값으로 기동을 막지 않음 |
HLS를 꺼 둔 서버에 같은 제약을 무조건 적용하지 않은 것도 선택의 일부입니다. 사용하지 않는 기능의 설정값이 다른 서버 기능의 기동까지 막지 않게, 기존 HLS 검증과 같은 활성화 조건 안에서 검사했습니다.
실패하는 입력만 확인하면 검증이 과해질 수 있다
검증을 추가하면 잘못된 값이 거부되는지는 쉽게 확인할 수 있습니다. 그러나 정상 입력까지 막으면 새 회귀를 만듭니다. 그래서 최소값 바로 아래와 최소값 자체를 짝으로 확인했습니다.
lowLatency 6, fMP4 2, MPEG-TS 2는 시작 단계에서 exit 1로 거부됐고, 각각 7·3·3은 정상 기동했습니다. 설정 테스트에도 이 6개 경계 사례를 추가했습니다. 특히 lowLatency 7은 30초 실제 라이브 송출 동안 먹서 실패 0과 재생 목록 응답을 확인했습니다. 단순히 설정 검사만 통과하는 데서 끝나지 않고 하위 라이브러리로 연결되는 경계값을 검증한 것입니다.
| 관측 | 수정 전 | 수정 후 확인 |
|---|---|---|
| LL-HLS 조각 수 6 | 기동 후 송출에서 먹서 실패 | 기동 단계에서 오류 거부 |
| 자동 재생성 | 40초 관측에 실패 5회 | 잘못된 구성으로 실행을 시작하지 않음 |
| LL-HLS 조각 수 7 | 정상이어야 할 경계 | 30초 송출, 먹서 실패 0·목록 응답 |
6개 경계 테스트는 거부할 값을 막으면서 정상 경계는 남겼는지를 확인합니다. 30초 송출은 허용한 경계값이 하위 먹서에서도 실제로 동작하는지 확인합니다. 검증 대상을 이 두 질문으로 나눠, 검사만 엄격해지고 재생은 여전히 실패하는 변경을 피하려 했습니다.
0이라는 입력의 호환성도 명시했다
기존에는 hlsSegmentCount: 0을 하위 라이브러리가 기본값 7로 치환했습니다. 새 하한 검증에서는 0도 오류로 거부됩니다. 흔히 잘못된 입력을 빨리 막는 변경은 순수한 안전성 개선처럼 보이지만, 기존에 동작하던 설정 일부를 거부하는 호환성 변화이기도 합니다. 이 점을 PR에 명시했습니다.
변경 후 조각 수 6은 방송이 들어올 때까지 잠복하지 않고 기동 단계에서 필요한 최소값과 함께 거부됩니다. 기존에 허용하던 0도 막는 호환성 비용은 있지만, 사용자가 네트워크나 방송 입력을 조사하기 전에 고칠 설정을 알 수 있습니다. 재시도로 회복되지 않는 제약을 앞단의 입력 계약에 넣는 것이 이번 수정의 효과였습니다.
이 글은 PokeClip·MediaMTX 기술 기록 모음의 일부입니다. 포트폴리오 전체본 37쪽에서 연결된 사례도 함께 볼 수 있습니다.