decoder_decode.go

package gopus

import (
	"github.com/thesyncim/gopus/internal/extsupport"
	"github.com/thesyncim/gopus/silk"
)

// Decode decodes an Opus packet into float32 PCM samples.
//
// data: Opus packet data, or nil for Packet Loss Concealment (PLC).
// pcm: Output buffer for decoded samples. Must be large enough to hold
// frameSize * frameCount * channels samples, where frameSize and frameCount
// are determined from the packet TOC and frame code.
//
// Returns the number of samples per channel decoded, or an error.
//
// When data is nil, the decoder performs packet loss concealment using
// the last successfully decoded frame parameters. Before the first packet has
// been decoded, cold PLC returns zeroed audio and a nil error.
//
// Buffer sizing: For 60ms frames at 48kHz stereo, pcm must have at least
// 2880 * 2 = 5760 elements. For multi-frame packets (code 1/2/3), the buffer
// must be large enough for all frames combined.
//
// Multi-frame packets (RFC 6716 Section 3.2):
//   - Code 0: 1 frame (most common)
//   - Code 1: 2 equal-sized frames
//   - Code 2: 2 different-sized frames
//   - Code 3: Arbitrary number of frames (1-48)
func (d *Decoder) Decode(data []byte, pcm []float32) (int, error) {
	return d.decodeFloat32(data, pcm, true)
}

func (d *Decoder) decodeFloat32(data []byte, pcm []float32, clearSoftClipOnPacket bool) (int, error) {
	channels := int(d.channels)
	sampleRate := int(d.sampleRate)
	dredPossible := false
	if extsupport.DREDRuntime {
		dredPossible = d.dredDecodeSidecarPossible()
		if data != nil && len(data) > 0 && dredPossible && d.dredCachedPayloadActive() {
			d.invalidateDREDPayloadState()
		}
	}

	if data == nil || len(data) == 0 {
		frameSize, err := d.plcOutputFrameSize(len(pcm))
		if err != nil {
			return 0, err
		}
		packetFrameSize := int(d.lastFrameSize)
		if packetFrameSize <= 0 {
			packetFrameSize = frameSize
		}
		neuralReady := dredPossible && d.dredNeuralConcealmentAvailable()
		n := frameSize
		usedNeuralConcealment := false
		if neuralReady && d.prevMode == ModeSILK && channels >= 1 && channels <= 2 {
			n, usedNeuralConcealment, err = d.decodeSILKNeuralPLCInto(pcm, frameSize, plcDecodeState{
				packetFrameSize:    packetFrameSize,
				mode:               d.prevMode,
				bandwidth:          d.lastBandwidth,
				packetStereo:       d.prevPacketStereo,
				useDecoderPLCState: true,
			})
		}
		if err != nil {
			return 0, err
		}
		if !usedNeuralConcealment && neuralReady && sampleRate == 16000 && channels >= 1 && channels <= 2 && d.prevMode != ModeHybrid && d.prevMode != ModeSILK {
			if len(pcm) < frameSize*channels {
				return 0, ErrBufferTooSmall
			}
			usedNeuralConcealment = d.applyDREDNeuralConcealment(pcm[:frameSize*channels], frameSize)
		}
		if !usedNeuralConcealment && dredPossible {
			n, usedNeuralConcealment, err = d.decodeDRED48kNeuralPLCInto(pcm, frameSize, plcDecodeState{
				packetFrameSize:    packetFrameSize,
				mode:               d.prevMode,
				bandwidth:          d.lastBandwidth,
				packetStereo:       d.prevPacketStereo,
				useDecoderPLCState: true,
			})
		} else if !usedNeuralConcealment {
			n, err = d.decodePLCChunksInto(pcm, frameSize, plcDecodeState{
				packetFrameSize:    packetFrameSize,
				mode:               d.prevMode,
				bandwidth:          d.lastBandwidth,
				packetStereo:       d.prevPacketStereo,
				useDecoderPLCState: true,
			})
		}
		if err != nil {
			return 0, err
		}
		frameSize = n
		if neuralReady && !usedNeuralConcealment && d.prevMode == ModeCELT {
			usedNeuralConcealment = d.applyDREDNeuralConcealment(pcm[:frameSize*channels], frameSize)
		}
		// libopus enables OSCE_MODE_SILK_BBWE during PLC whenever the
		// internal sample rate is 16 kHz and the API sample rate is 48 kHz
		// (`data == NULL` branch in opus_decoder.c). The gopus equivalent
		// gate uses the previous packet's mode/bandwidth as the BWE
		// eligibility signal: only SILK WB carries the 16 kHz internal SR
		// that BWE expects. Stereo and DRED neural concealment paths are
		// intentionally excluded so the BWE never overwrites richer
		// concealment output.
		//
		// LACE/NoLACE does not enhance packet-loss frames in libopus:
		// `silk_decode_frame` calls `osce_reset` on the lost branch.
		// Keep that state transition here before optional BWE runs on the
		// concealed SILK lowband.
		if extsupport.OSCERuntime {
			packetStereoLocal := d.prevPacketStereo
			if d.lastPacketMode == ModeSILK &&
				d.lastBandwidth == BandwidthWideband &&
				sampleRate == 48000 && d.osceLACEActive() {
				d.resetOSCELACEPostfilterState(packetStereoLocal)
			}
			if !usedNeuralConcealment && d.lastPacketMode == ModeSILK &&
				d.lastBandwidth == BandwidthWideband &&
				sampleRate == 48000 && d.osceBWEActive() {
				d.maybeApplyOSCEBWEPostSilk(pcm[:frameSize*channels], frameSize, ModeSILK, silk.BandwidthWideband, packetStereoLocal)
			}
		}
		d.applyOutputGain(pcm[:frameSize*channels])

		d.lastFrameSize = int32(packetFrameSize)
		d.lastPacketDuration = int32(frameSize)
		d.lastDataLen = 0
		if dredPossible && !usedNeuralConcealment && d.dredGoodPacketMarkerActive() {
			d.markDREDConcealed()
		}
		return frameSize, nil
	}

	if len(data) > d.maxPacketBytes {
		return 0, ErrPacketTooLarge
	}

	tocValue, frameCount, err := packetFrameCount(data)
	if err != nil {
		return 0, err
	}
	toc := &tocValue
	frameCode := data[0] & 0x03
	frameSize := toc.FrameSize
	if toc.Mode == ModeSILK || toc.Mode == ModeCELT || toc.Mode == ModeHybrid {
		frameSize = packetTOCSamplesPerFrameAtRate(data[0], sampleRate)
	}
	totalSamples := frameSize * frameCount
	if totalSamples > d.maxPacketSamples {
		return 0, ErrPacketTooLarge
	}

	needed := totalSamples * channels
	if len(pcm) < needed {
		return 0, ErrBufferTooSmall
	}

	if dredPossible {
		if endRawDREDCapture := d.beginDREDRawMonoGoodFrameCapture(toc.Mode); endRawDREDCapture != nil {
			defer endRawDREDCapture()
		}
	}

	if frameCode == 0 {
		_, err := d.decodeOpusFrameIntoWithQEXT(
			pcm,
			data[1:],
			frameSize,
			frameSize,
			toc.Mode,
			toc.Bandwidth,
			toc.Stereo,
			nil,
		)
		if err != nil {
			return 0, err
		}
		d.prevPacketStereo = toc.Stereo
	} else {
		_, err := d.decodeMultiFrameFloat32(pcm, data, toc, frameCode, frameSize)
		if err != nil {
			return 0, err
		}
	}

	// OSCE BWE transition bookkeeping: when the current packet does not
	// satisfy OSCE_MODE_SILK_BBWE (Hybrid or mono SILK NB/MB), clear the
	// previous-BWE-active flag so the next SILK WB packet does not
	// erroneously fade in. The SILK-only post-decode hook handles the
	// SILK -> SILK cross-fade itself; this catches Hybrid and CELT
	// transitions where the SILK helper is not invoked.
	if extsupport.OSCERuntime {
		d.osceBWEMarkInactiveIfModeIneligible(toc.Mode, toc.Bandwidth, pcm[:totalSamples*channels], totalSamples, toc.Stereo)
	}

	// OSCE LACE/NoLACE transition bookkeeping: clear the previous-LACE-
	// active flag when the current packet bypasses the postfilter (Hybrid
	// or CELT). Mirrors libopus `osce_reset` which gets called whenever
	// `osce_enhance_frame` exits early (e.g. fs_kHz != 16), priming the
	// reset counter so the next LACE-active frame runs the cross-fade.
	if extsupport.OSCERuntime {
		d.osceLACEMarkInactiveIfModeIneligible(toc.Mode, toc.Bandwidth)
	}

	d.lastFrameSize = int32(frameSize)
	d.lastPacketDuration = int32(totalSamples)
	d.lastBandwidth = toc.Bandwidth
	d.lastPacketMode = toc.Mode
	d.lastDataLen = int32(len(data))

	d.clearFECState()

	if dredPossible {
		if d.dredPayloadScannerActive() {
			d.maybeCacheDREDPayload(data)
		}
		if d.dredGoodPacketMarkerActive() {
			if r := d.dredRecoveryState(); r != nil && d.dredNeuralModelsLoaded() {
				r.dredRecovery = 0
			}
			d.markDREDUpdatedPCM(pcm[:totalSamples*channels], totalSamples, toc.Mode)
		}
	}
	d.applyOutputGain(pcm[:totalSamples*channels])
	if clearSoftClipOnPacket {
		d.clearSoftClipMem()
	}
	return totalSamples, nil
}

func (d *Decoder) decodeMultiFrameFloat32(pcm []float32, data []byte, toc *TOC, frameCode byte, frameSize int) (int, error) {
	channels := int(d.channels)
	offsetSamples := 0
	var qextPayloads decoderQEXTPayloads
	decodeFrame := func(frameIndex int, frameData []byte) error {
		var qextPayload []byte
		if extsupport.QEXT && !d.ignoreExtensions {
			qextPayload = qextPayloads.frame(frameIndex)
		}
		n, err := d.decodeOpusFrameIntoWithQEXT(
			pcm[offsetSamples*channels:],
			frameData,
			frameSize,
			frameSize,
			toc.Mode,
			toc.Bandwidth,
			toc.Stereo,
			qextPayload,
		)
		if err != nil {
			return err
		}
		offsetSamples += n
		d.prevPacketStereo = toc.Stereo
		return nil
	}

	switch frameCode {
	case 1:
		frameDataLen := len(data) - 1
		if frameDataLen%2 != 0 {
			return 0, ErrInvalidPacket
		}
		frameLen := frameDataLen / 2
		offset := 1
		for i := 0; i < 2; i++ {
			if offset+frameLen > len(data) {
				return 0, ErrInvalidPacket
			}
			if err := decodeFrame(i, data[offset:offset+frameLen]); err != nil {
				return 0, err
			}
			offset += frameLen
		}
	case 2:
		if len(data) < 2 {
			return 0, ErrPacketTooShort
		}
		frame1Len, bytesRead, err := parseFrameLength(data, 1)
		if err != nil {
			return 0, err
		}
		headerLen := 1 + bytesRead
		frame2Len := len(data) - headerLen - frame1Len
		if frame2Len < 0 {
			return 0, ErrInvalidPacket
		}
		if headerLen+frame1Len > len(data) {
			return 0, ErrInvalidPacket
		}
		if err := decodeFrame(0, data[headerLen:headerLen+frame1Len]); err != nil {
			return 0, err
		}
		offset := headerLen + frame1Len
		if offset+frame2Len > len(data) {
			return 0, ErrInvalidPacket
		}
		if err := decodeFrame(1, data[offset:offset+frame2Len]); err != nil {
			return 0, err
		}
	case 3:
		if len(data) < 2 {
			return 0, ErrPacketTooShort
		}
		frameCountByte := data[1]
		vbr := (frameCountByte & 0x80) != 0
		hasPadding := (frameCountByte & 0x40) != 0
		m := int(frameCountByte & 0x3F)
		if m == 0 || m > 48 {
			return 0, ErrInvalidFrameCount
		}

		offset := 2
		padding := 0

		if hasPadding {
			for {
				if offset >= len(data) {
					return 0, ErrPacketTooShort
				}
				padByte := int(data[offset])
				offset++
				if padByte == 255 {
					padding += 254
				} else {
					padding += padByte
				}
				if padByte < 255 {
					break
				}
			}
			if extsupport.QEXT && !d.ignoreExtensions && toc.Mode != ModeSILK {
				if padding > len(data) {
					return 0, ErrInvalidPacket
				}
				qextPayloads.collect(data[len(data)-padding:], m, qextPacketExtensionID)
			}
		}

		if vbr {
			var frameLens [48]int
			for i := 0; i < m-1; i++ {
				frameLen, bytesRead, err := parseFrameLength(data, offset)
				if err != nil {
					return 0, err
				}
				offset += bytesRead
				frameLens[i] = frameLen
			}
			frameDataOffset := offset
			for i := 0; i < m-1; i++ {
				frameLen := frameLens[i]
				if frameDataOffset+frameLen > len(data)-padding {
					return 0, ErrInvalidPacket
				}
				if err := decodeFrame(i, data[frameDataOffset:frameDataOffset+frameLen]); err != nil {
					return 0, err
				}
				frameDataOffset += frameLen
			}
			lastFrameLen := len(data) - frameDataOffset - padding
			if lastFrameLen < 0 {
				return 0, ErrInvalidPacket
			}
			if frameDataOffset+lastFrameLen > len(data)-padding {
				return 0, ErrInvalidPacket
			}
			if err := decodeFrame(m-1, data[frameDataOffset:frameDataOffset+lastFrameLen]); err != nil {
				return 0, err
			}
		} else {
			frameDataLen := len(data) - offset - padding
			if frameDataLen < 0 {
				return 0, ErrInvalidPacket
			}
			if frameDataLen%m != 0 {
				return 0, ErrInvalidPacket
			}
			frameLen := frameDataLen / m
			for i := 0; i < m; i++ {
				if offset+frameLen > len(data)-padding {
					return 0, ErrInvalidPacket
				}
				if err := decodeFrame(i, data[offset:offset+frameLen]); err != nil {
					return 0, err
				}
				offset += frameLen
			}
		}
	}

	return offsetSamples, nil
}

// DecodeWithFEC decodes an Opus packet, optionally recovering a lost frame using FEC.
//
// This mirrors libopus decode_fec semantics: when fec is true, the decoder
// uses in-band LBRR data if present and otherwise falls back to packet loss
// concealment instead of returning a missing-FEC error.
func (d *Decoder) DecodeWithFEC(data []byte, pcm []float32, fec bool) (int, error) {
	if !fec {
		return d.Decode(data, pcm)
	}
	sampleRate := int(d.sampleRate)

	if data != nil && len(data) > 0 {
		toc, frameCount, err := packetFrameCount(data)
		if err != nil {
			return 0, err
		}
		requestedFrameSize, err := d.requestedOutputFrameSize(len(pcm))
		if err != nil {
			return 0, err
		}
		frameSize := toc.FrameSize
		if toc.Mode == ModeSILK || toc.Mode == ModeCELT || toc.Mode == ModeHybrid {
			frameSize = packetTOCSamplesPerFrameAtRate(data[0], sampleRate)
		}
		if frameSize <= 0 {
			frameSize = int(d.lastFrameSize)
		}
		if frameSize <= 0 {
			frameSize = sampleRate / 50
		}

		prevPacketMode := d.lastPacketMode
		if requestedFrameSize < frameSize || toc.Mode == ModeCELT || prevPacketMode == ModeCELT {
			d.clearFECState()
			plcSize, err := d.plcOutputFrameSize(len(pcm))
			if err != nil {
				return 0, err
			}
			return d.decodePLCForFEC(pcm, plcSize)
		}
		d.lastPacketMode = toc.Mode

		if toc.Mode == ModeSILK || toc.Mode == ModeHybrid {
			firstFrameData, err := extractFirstFramePayload(data, toc)
			if err != nil {
				return 0, err
			}
			if !packetHasLBRR(firstFrameData, toc) {
				d.clearFECState()
				if extsupport.DREDRuntime && d.dredCachedPayloadActive() {
					return d.decodePLCForFECWithState(pcm, requestedFrameSize, frameSize, toc.Mode, toc.Bandwidth, toc.Stereo)
				}
				return d.decodeNoLBRRFECFallback(pcm, requestedFrameSize, frameSize, toc.Mode, toc.Bandwidth, toc.Stereo)
			}
			d.storeFECData(firstFrameData, toc, frameCount, frameSize)
			if n, err := d.decodeFECFrame(pcm, requestedFrameSize); err == nil {
				return n, nil
			}
			d.clearFECState()
		}
		return d.decodePLCForFECWithState(pcm, requestedFrameSize, frameSize, toc.Mode, toc.Bandwidth, toc.Stereo)
	}

	d.clearFECState()
	frameSize, err := d.plcOutputFrameSize(len(pcm))
	if err != nil {
		return 0, err
	}
	return d.decodePLCForFEC(pcm, frameSize)
}

// DecodeInt16 decodes an Opus packet into int16 PCM samples.
func (d *Decoder) DecodeInt16(data []byte, pcm []int16) (int, error) {
	channels := int(d.channels)
	sampleRate := int(d.sampleRate)
	if data == nil || len(data) == 0 {
		frameSize, err := d.plcOutputFrameSize(len(pcm))
		if err != nil {
			return 0, err
		}

		needed := frameSize * channels
		d.ensureScratchPCM(needed)
		n, err := d.decodeFloat32(data, d.scratchPCM, false)
		if err != nil {
			return 0, err
		}
		float32ToInt16NoSoftClip(pcm, d.scratchPCM, n, channels)
		return n, nil
	}

	if len(data) > d.maxPacketBytes {
		return 0, ErrPacketTooLarge
	}

	if len(pcm) >= d.maxPacketSamples*channels {
		d.ensureScratchPCM(d.maxPacketSamples * channels)
		n, err := d.decodeFloat32(data, d.scratchPCM, false)
		if err != nil {
			return 0, err
		}
		softClipAndFloat32ToInt16(pcm, d.scratchPCM, n, channels, d.softClipMem[:])
		return n, nil
	}

	toc, frameCount, err := packetFrameCount(data)
	if err != nil {
		return 0, err
	}
	frameSize := toc.FrameSize
	if toc.Mode == ModeSILK || toc.Mode == ModeCELT || toc.Mode == ModeHybrid {
		frameSize = packetTOCSamplesPerFrameAtRate(data[0], sampleRate)
	}
	totalSamples := frameSize * frameCount
	if totalSamples > d.maxPacketSamples {
		return 0, ErrPacketTooLarge
	}
	needed := totalSamples * channels
	if len(pcm) < needed {
		return 0, ErrBufferTooSmall
	}

	d.ensureScratchPCM(needed)
	n, err := d.decodeFloat32(data, d.scratchPCM, false)
	if err != nil {
		return 0, err
	}
	softClipAndFloat32ToInt16(pcm, d.scratchPCM, n, channels, d.softClipMem[:])
	return n, nil
}

func (d *Decoder) ensureScratchPCM(needed int) {
	if cap(d.scratchPCM) < needed {
		d.scratchPCM = make([]float32, needed)
		return
	}
	d.scratchPCM = d.scratchPCM[:needed]
}