Implement periodic CELT packet loss concealment and recovery

.github/workflows/plc-quality.yml

@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: 2026 The Pion community <https://pion.ly>
+# SPDX-License-Identifier: MIT
+name: PLC quality
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  compare:
+    name: Before/after (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: current
+      - uses: actions/checkout@v7
+        with:
+          repository: pion/opus
+          ref: c0d7ee63cecdc35aa81b83cbde40c70148da9e74
+          path: baseline
+      - uses: actions/setup-go@v7
+        with:
+          go-version: '1.25'
+          cache-dependency-path: current/go.sum
+      - name: Measure unchanged base with the same compiler and race mode
+        working-directory: baseline
+        env:
+          PLC_CORPUS_PATH: ${{ github.workspace }}/current/testdata/short-plc/corpus.json.gz
+          PLC_BASELINE_OUTPUT: ${{ runner.temp }}/plc-baseline.json
+        run: |
+          cp ../current/decoder_plc_corpus_test.go ../current/decoder_plc_race_test.go ../current/decoder_plc_norace_test.go .
+          go test -race -run '^TestPLCCorpus$' -count=1 .
+      - name: Require exact no-loss PCM and loss/recovery improvement
+        working-directory: current
+        env:
+          PLC_BASELINE_PATH: ${{ runner.temp }}/plc-baseline.json
+        run: go test -race -run '^TestPLCCorpus$' -count=1 .
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: plc-baseline-${{ matrix.os }}
+          path: ${{ runner.temp }}/plc-baseline.json
+          if-no-files-found: error

LICENSES/BSD-2-Clause.txt

@@ -0,0 +1,22 @@
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

decoder_plc_bench_test.go

@@ -0,0 +1,143 @@
+// SPDX-FileCopyrightText: 2026 The Pion community <https://pion.ly>
+// SPDX-License-Identifier: MIT
+
+package opus
+
+import (
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func plcBenchmarkPackets(tb testing.TB, channels int) [][]byte {
+	tb.Helper()
+	var fixture plcCorpus
+	path := os.Getenv("PLC_SHORT_FIXTURE")
+	if path == "" {
+		path = "testdata/short-plc/libopus.json"
+	}
+	data, err := os.ReadFile(path) //nolint:gosec // Explicit offline benchmark fixture.
+	require.NoError(tb, err)
+	require.NoError(tb, json.Unmarshal(data, &fixture))
+	packets := make([][]byte, 3)
+	for i := range packets {
+		packets[i], err = hex.DecodeString(fixture.Cases[(channels-1)*4].Steps[i].Packet)
+		require.NoError(tb, err)
+	}
+
+	return packets
+}
+
+func BenchmarkCELTPLC(b *testing.B) {
+	for _, channels := range []int{1, 2} {
+		packets := plcBenchmarkPackets(b, channels)
+		for _, scenario := range []struct {
+			name        string
+			priorLosses int
+		}{
+			{"normal", -1}, {"first", 0}, {"periodic", 1}, {"noise", 6},
+		} {
+			b.Run(fmt.Sprintf("%dch/%s", channels, scenario.name), func(b *testing.B) {
+				decoder, err := NewDecoderWithOutput(48000, channels)
+				require.NoError(b, err)
+				out := make([]int16, 960*channels)
+				prime := func() {
+					for _, packet := range packets {
+						_, err = decoder.DecodeToInt16(packet, out)
+						require.NoError(b, err)
+					}
+				}
+				prime()
+				require.NoError(b, decoder.DecodePLC(out))
+				b.ReportAllocs()
+				b.ResetTimer()
+				for range b.N {
+					b.StopTimer()
+					prime()
+					for range max(0, scenario.priorLosses) {
+						require.NoError(b, decoder.DecodePLC(out))
+					}
+					b.StartTimer()
+					if scenario.priorLosses < 0 {
+						_, err = decoder.DecodeToInt16(packets[2], out)
+					} else {
+						err = decoder.DecodePLC(out)
+					}
+					if err != nil {
+						b.Fatal(err)
+					}
+				}
+			})
+		}
+	}
+}
+
+func TestCELTPLCWarmAllocations(t *testing.T) {
+	for _, channels := range []int{1, 2} {
+		packets := plcBenchmarkPackets(t, channels)
+		decoder, err := NewDecoderWithOutput(48000, channels)
+		require.NoError(t, err)
+		out := make([]int16, 1920)
+		cycle := func() {
+			for _, packet := range packets {
+				_, err = decoder.DecodeToInt16(packet, out)
+				require.NoError(t, err)
+			}
+			for range 7 {
+				require.NoError(t, decoder.DecodePLC(out[:960*channels]))
+			}
+		}
+		cycle()
+		require.Zero(t, testing.AllocsPerRun(100, cycle))
+	}
+}
+
+func TestCELTPLCResetAndDecoderIsolation(t *testing.T) {
+	for _, channels := range []int{1, 2} {
+		packets := plcBenchmarkPackets(t, channels)
+		for _, losses := range []int{1, 7} {
+			t.Run(fmt.Sprintf("%dch/%dlosses", channels, losses), func(t *testing.T) {
+				decoder, err := NewDecoderWithOutput(48000, channels)
+				require.NoError(t, err)
+				control, err := NewDecoderWithOutput(48000, channels)
+				require.NoError(t, err)
+				unrelated, err := NewDecoderWithOutput(48000, channels)
+				require.NoError(t, err)
+				actual, expected, other := make([]int16, 960*channels), make([]int16, 960*channels), make([]int16, 960*channels)
+				for _, packet := range packets {
+					_, err = decoder.DecodeToInt16(packet, actual)
+					require.NoError(t, err)
+					_, err = unrelated.DecodeToInt16(packet, other)
+					require.NoError(t, err)
+				}
+				for range losses {
+					require.NoError(t, decoder.DecodePLC(actual))
+				}
+				// Init calls the CELT core's Reset, including periodic history,
+				// LPC, background energy, pending overlap and noise skip state.
+				require.NoError(t, decoder.Init(48000, channels))
+				for step := range 20 {
+					// Interleave another live decoder to expose shared scratch/state.
+					require.NoError(t, unrelated.DecodePLC(other))
+					if step >= 3 && step < 10 {
+						require.NoError(t, decoder.DecodePLC(actual))
+						require.NoError(t, control.DecodePLC(expected))
+					} else {
+						clear(actual)
+						clear(expected)
+						_, err = decoder.DecodeToInt16(packets[step%len(packets)], actual)
+						require.NoError(t, err)
+						_, err = control.DecodeToInt16(packets[step%len(packets)], expected)
+						require.NoError(t, err)
+					}
+					require.Equal(t, expected, actual, "step %d", step)
+					require.Equal(t, control.rangeFinal, decoder.rangeFinal)
+				}
+			})
+		}
+	}
+}

decoder_plc_corpus_test.go

@@ -0,0 +1,147 @@
+// SPDX-FileCopyrightText: 2026 The Pion community <https://pion.ly>
+// SPDX-License-Identifier: MIT
+
+//nolint:cyclop,varnamelen,tagliatelle // Table-driven reference corpus with explicit baseline recording.
+package opus
+
+import (
+	"bytes"
+	"compress/gzip"
+	"crypto/sha256"
+	"encoding/binary"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"math"
+	"os"
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+type plcCorpus struct {
+	Pin   string
+	Cases []struct {
+		Signal, Channels, Rate, Mode, Sequence int
+		OutputChannels                         int `json:"output_channels"`
+		Steps                                  []struct {
+			Packet  string
+			Samples int
+			Range   uint32
+			PCM     []int16
+		}
+	}
+}
+type plcMeasurement struct {
+	RMSE float64
+	Peak int
+	Hash string
+}
+
+func readPLCBaseline(t *testing.T) [][]plcMeasurement {
+	t.Helper()
+	baselinePath := "testdata/short-plc/baseline.json"
+	compressed := runtime.GOARCH == "arm64"
+	if compressed {
+		baselinePath = "testdata/short-plc/baseline-arm64.json.gz"
+	}
+	if compressed && plcBaselineRace {
+		baselinePath = "testdata/short-plc/baseline-arm64-race.json.gz"
+	}
+	if path := os.Getenv("PLC_BASELINE_PATH"); path != "" {
+		baselinePath, compressed = path, false
+	}
+	data, err := os.ReadFile(baselinePath) //nolint:gosec // Explicit offline same-build baseline for CI comparison.
+	require.NoError(t, err)
+	var baseline [][]plcMeasurement
+	if compressed {
+		reader, err := gzip.NewReader(bytes.NewReader(data))
+		require.NoError(t, err)
+		require.NoError(t, json.NewDecoder(reader).Decode(&baseline))
+		require.NoError(t, reader.Close())
+	} else {
+		require.NoError(t, json.Unmarshal(data, &baseline))
+	}
+
+	return baseline
+}
+
+func TestPLCCorpus(t *testing.T) {
+	path := os.Getenv("PLC_CORPUS_PATH")
+	if path == "" {
+		path = "testdata/short-plc/corpus.json.gz"
+	}
+	f, err := os.Open(path) //nolint:gosec // Operator-supplied offline fixture path for baseline generation.
+	require.NoError(t, err)
+	defer f.Close() //nolint:errcheck
+	z, err := gzip.NewReader(f)
+	require.NoError(t, err)
+	defer z.Close() //nolint:errcheck
+	var corpus plcCorpus
+	require.NoError(t, json.NewDecoder(z).Decode(&corpus))
+	require.Equal(t, "22244de5a79bd1d6d623c32e72bf1954b56235be", corpus.Pin)
+	var baseline [][]plcMeasurement
+	record := os.Getenv("PLC_BASELINE_OUTPUT")
+	if record == "" {
+		baseline = readPLCBaseline(t)
+		require.Len(t, baseline, len(corpus.Cases))
+	}
+	results := make([][]plcMeasurement, len(corpus.Cases))
+	for ci, c := range corpus.Cases {
+		name := fmt.Sprintf("%03d/signal%d/%dto%d/%d/mode%d/sequence%d",
+			ci, c.Signal, c.Channels, c.OutputChannels, c.Rate, c.Mode, c.Sequence)
+		t.Run(name, func(t *testing.T) {
+			d, err := NewDecoderWithOutput(c.Rate, c.OutputChannels)
+			require.NoError(t, err)
+			var currentError, oldError float64
+			results[ci] = make([]plcMeasurement, len(c.Steps))
+			for si, s := range c.Steps {
+				out := make([]int16, s.Samples*c.OutputChannels)
+				if s.Packet == "" {
+					require.NoError(t, d.DecodePLC(out))
+				} else {
+					p, err := hex.DecodeString(s.Packet)
+					require.NoError(t, err)
+					n, err := d.DecodeToInt16(p, out)
+					require.NoError(t, err)
+					require.Equal(t, s.Samples, n)
+				}
+				require.Equal(t, s.Range, d.rangeFinal, "step %d", si)
+				require.Len(t, s.PCM, len(out))
+				m := plcMeasurement{}
+				var squared float64
+				bytes := make([]byte, 2*len(out))
+				for i, v := range out {
+					delta := int(v) - int(s.PCM[i])
+					squared += float64(delta) * float64(delta)
+					m.Peak = max(m.Peak, int(math.Abs(float64(delta))))
+					binary.LittleEndian.PutUint16(bytes[i*2:], uint16(v))
+				}
+				hash := sha256.Sum256(bytes)
+				m.Hash = hex.EncodeToString(hash[:])
+				m.RMSE = math.Sqrt(squared / float64(len(out)))
+				results[ci][si] = m
+				if record == "" {
+					b := baseline[ci][si]
+					require.LessOrEqual(t, m.RMSE, b.RMSE+1, "step %d: RMSE %.6f vs baseline %.6f", si, m.RMSE, b.RMSE)
+					if c.Sequence == 2 || si < 4 {
+						require.Equal(t, b.Hash, m.Hash, "no-loss PCM changed, step %d", si)
+					}
+					if si >= 4 {
+						currentError += squared
+						oldError += b.RMSE * b.RMSE * float64(len(out))
+					}
+				}
+			}
+			if record == "" && c.Mode == 0 && c.Signal < 3 && c.Sequence != 2 {
+				require.LessOrEqual(t, currentError, oldError/4, "halve aggregate periodic error")
+			}
+		})
+	}
+	if record != "" {
+		data, err := json.Marshal(results)
+		require.NoError(t, err)
+		require.NoError(t, os.WriteFile(record, data, 0o600)) //nolint:gosec // Explicit offline baseline output.
+	}
+}

decoder_plc_norace_test.go

@@ -0,0 +1,8 @@
+// SPDX-FileCopyrightText: 2026 The Pion community <https://pion.ly>
+// SPDX-License-Identifier: MIT
+
+//go:build !race
+
+package opus
+
+const plcBaselineRace = false

decoder_plc_race_test.go

@@ -0,0 +1,8 @@
+// SPDX-FileCopyrightText: 2026 The Pion community <https://pion.ly>
+// SPDX-License-Identifier: MIT
+
+//go:build race
+
+package opus
+
+const plcBaselineRace = true