From 8857e25353deba665a2bc793abe953898263ce6c Mon Sep 17 00:00:00 2001
From: aler9 <46489434+aler9@users.noreply.github.com>
Date: Mon, 14 Aug 2023 13:22:26 +0200
Subject: [PATCH] deprecate rtpav1.Decoder.Decode, rtph264.Decoder.Decode,
 rtph265.Decoder.Decode

---
 .../main.go                                   |  2 +-
 .../main.go                                   |  1 -
 examples/client-read-format-h264/main.go      |  2 +-
 examples/client-read-format-h265/main.go      |  2 +-
 pkg/formats/av1_test.go                       |  2 +-
 pkg/formats/h264_test.go                      |  2 +-
 pkg/formats/h265_test.go                      |  2 +-
 pkg/formats/rtpav1/decoder.go                 | 12 +++++++----
 pkg/formats/rtpav1/decoder_test.go            |  6 +++---
 pkg/formats/rtph264/decoder.go                | 12 +++++++----
 pkg/formats/rtph264/decoder_test.go           | 20 +++++++++----------
 pkg/formats/rtph265/decoder.go                | 12 +++++++----
 pkg/formats/rtph265/decoder_test.go           |  6 +++---
 13 files changed, 46 insertions(+), 35 deletions(-)

diff --git a/examples/client-read-format-h264-convert-to-jpeg/main.go b/examples/client-read-format-h264-convert-to-jpeg/main.go
index 8fe2d2c0..abfb7582 100644
--- a/examples/client-read-format-h264-convert-to-jpeg/main.go
+++ b/examples/client-read-format-h264-convert-to-jpeg/main.go
@@ -101,7 +101,7 @@ func main() {
 	saveCount := 0
 	c.OnPacketRTP(medi, forma, func(pkt *rtp.Packet) {
 		// extract access units from RTP packets
-		au, _, err := rtpDec.Decode(pkt)
+		au, _, err := rtpDec.DecodeUntilMarker(pkt)
 		if err != nil {
 			if err != rtph264.ErrNonStartingPacketAndNoPrevious && err != rtph264.ErrMorePacketsNeeded {
 				log.Printf("ERR: %v", err)
diff --git a/examples/client-read-format-h264-save-to-disk/main.go b/examples/client-read-format-h264-save-to-disk/main.go
index 708daf3e..90b89023 100644
--- a/examples/client-read-format-h264-save-to-disk/main.go
+++ b/examples/client-read-format-h264-save-to-disk/main.go
@@ -65,7 +65,6 @@ func main() {
 	// called when a RTP packet arrives
 	c.OnPacketRTP(medi, forma, func(pkt *rtp.Packet) {
 		// extract access unit from RTP packets
-		// DecodeUntilMarker is necessary for the DTS extractor to work
 		au, pts, err := rtpDec.DecodeUntilMarker(pkt)
 		if err != nil {
 			if err != rtph264.ErrNonStartingPacketAndNoPrevious && err != rtph264.ErrMorePacketsNeeded {
diff --git a/examples/client-read-format-h264/main.go b/examples/client-read-format-h264/main.go
index 46b2855c..e5a622f4 100644
--- a/examples/client-read-format-h264/main.go
+++ b/examples/client-read-format-h264/main.go
@@ -77,7 +77,7 @@ func main() {
 	// called when a RTP packet arrives
 	c.OnPacketRTP(medi, forma, func(pkt *rtp.Packet) {
 		// extract access units from RTP packets
-		au, pts, err := rtpDec.Decode(pkt)
+		au, pts, err := rtpDec.DecodeUntilMarker(pkt)
 		if err != nil {
 			if err != rtph264.ErrNonStartingPacketAndNoPrevious && err != rtph264.ErrMorePacketsNeeded {
 				log.Printf("ERR: %v", err)
diff --git a/examples/client-read-format-h265/main.go b/examples/client-read-format-h265/main.go
index 5b006265..ecbe0089 100644
--- a/examples/client-read-format-h265/main.go
+++ b/examples/client-read-format-h265/main.go
@@ -59,7 +59,7 @@ func main() {
 	// called when a RTP packet arrives
 	c.OnPacketRTP(medi, forma, func(pkt *rtp.Packet) {
 		// extract access units from RTP packets
-		au, pts, err := rtpDec.Decode(pkt)
+		au, pts, err := rtpDec.DecodeUntilMarker(pkt)
 		if err != nil {
 			if err != rtph265.ErrNonStartingPacketAndNoPrevious && err != rtph265.ErrMorePacketsNeeded {
 				log.Printf("ERR: %v", err)
diff --git a/pkg/formats/av1_test.go b/pkg/formats/av1_test.go
index 06e1511a..ce4d327b 100644
--- a/pkg/formats/av1_test.go
+++ b/pkg/formats/av1_test.go
@@ -29,7 +29,7 @@ func TestAV1DecEncoder(t *testing.T) {
 	dec, err := format.CreateDecoder2()
 	require.NoError(t, err)
 
-	byts, _, err := dec.Decode(pkts[0])
+	byts, _, err := dec.DecodeUntilMarker(pkts[0])
 	require.NoError(t, err)
 	require.Equal(t, [][]byte{{0x01, 0x02, 0x03, 0x04}}, byts)
 }
diff --git a/pkg/formats/h264_test.go b/pkg/formats/h264_test.go
index c9a9ced8..3497b0e8 100644
--- a/pkg/formats/h264_test.go
+++ b/pkg/formats/h264_test.go
@@ -57,7 +57,7 @@ func TestH264DecEncoder(t *testing.T) {
 	dec, err := format.CreateDecoder2()
 	require.NoError(t, err)
 
-	byts, _, err := dec.Decode(pkts[0])
+	byts, _, err := dec.DecodeUntilMarker(pkts[0])
 	require.NoError(t, err)
 	require.Equal(t, [][]byte{{0x01, 0x02, 0x03, 0x04}}, byts)
 }
diff --git a/pkg/formats/h265_test.go b/pkg/formats/h265_test.go
index b93b5258..2d59b698 100644
--- a/pkg/formats/h265_test.go
+++ b/pkg/formats/h265_test.go
@@ -60,7 +60,7 @@ func TestH265DecEncoder(t *testing.T) {
 	dec, err := format.CreateDecoder2()
 	require.NoError(t, err)
 
-	byts, _, err := dec.Decode(pkts[0])
+	byts, _, err := dec.DecodeUntilMarker(pkts[0])
 	require.NoError(t, err)
 	require.Equal(t, [][]byte{{0x01, 0x02, 0x03, 0x04}}, byts)
 }
diff --git a/pkg/formats/rtpav1/decoder.go b/pkg/formats/rtpav1/decoder.go
index 41c3a1a6..79fd4856 100644
--- a/pkg/formats/rtpav1/decoder.go
+++ b/pkg/formats/rtpav1/decoder.go
@@ -52,7 +52,13 @@ func (d *Decoder) Init() error {
 }
 
 // Decode decodes OBUs from a RTP packet.
+//
+// Deprecated: this method returns incomplete temporal units.
 func (d *Decoder) Decode(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
+	return d.decodeOBUs(pkt)
+}
+
+func (d *Decoder) decodeOBUs(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
 	var av1header codecs.AV1Packet
 	_, err := av1header.Unmarshal(pkt.Payload)
 	if err != nil {
@@ -126,11 +132,9 @@ func (d *Decoder) Decode(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
 	return obus, d.timeDecoder.Decode(pkt.Timestamp), nil
 }
 
-// DecodeUntilMarker decodes OBUs from a RTP packet and puts them in a buffer.
-// When a packet has the marker flag (meaning that all OBUs with the same PTS have
-// been received), the buffer is returned.
+// DecodeUntilMarker decodes a temporal unit from a RTP packet.
 func (d *Decoder) DecodeUntilMarker(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
-	obus, pts, err := d.Decode(pkt)
+	obus, pts, err := d.decodeOBUs(pkt)
 	if err != nil {
 		return nil, 0, err
 	}
diff --git a/pkg/formats/rtpav1/decoder_test.go b/pkg/formats/rtpav1/decoder_test.go
index efe2d3f2..e190b752 100644
--- a/pkg/formats/rtpav1/decoder_test.go
+++ b/pkg/formats/rtpav1/decoder_test.go
@@ -18,7 +18,7 @@ func TestDecode(t *testing.T) {
 			var obus [][]byte
 
 			for _, pkt := range ca.pkts {
-				addOBUs, _, err := d.Decode(pkt)
+				addOBUs, _, err := d.DecodeUntilMarker(pkt)
 				if err == ErrMorePacketsNeeded {
 					continue
 				}
@@ -59,7 +59,7 @@ func FuzzDecoder(f *testing.F) {
 		d := &Decoder{}
 		d.Init() //nolint:errcheck
 
-		d.Decode(&rtp.Packet{ //nolint:errcheck
+		d.DecodeUntilMarker(&rtp.Packet{ //nolint:errcheck
 			Header: rtp.Header{
 				Version:        2,
 				Marker:         am,
@@ -71,7 +71,7 @@ func FuzzDecoder(f *testing.F) {
 			Payload: a,
 		})
 
-		d.Decode(&rtp.Packet{ //nolint:errcheck
+		d.DecodeUntilMarker(&rtp.Packet{ //nolint:errcheck
 			Header: rtp.Header{
 				Version:        2,
 				Marker:         bm,
diff --git a/pkg/formats/rtph264/decoder.go b/pkg/formats/rtph264/decoder.go
index b9ee40a7..0a31f478 100644
--- a/pkg/formats/rtph264/decoder.go
+++ b/pkg/formats/rtph264/decoder.go
@@ -60,7 +60,13 @@ func (d *Decoder) Init() error {
 }
 
 // Decode decodes NALUs from a RTP packet.
+//
+// Deprecated: this method returns incomplete access units.
 func (d *Decoder) Decode(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
+	return d.decodeNALUs(pkt)
+}
+
+func (d *Decoder) decodeNALUs(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
 	if len(pkt.Payload) < 1 {
 		d.fragments = d.fragments[:0] // discard pending fragments
 		return nil, 0, fmt.Errorf("payload is too short")
@@ -170,11 +176,9 @@ func (d *Decoder) Decode(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
 	return nalus, d.timeDecoder.Decode(pkt.Timestamp), nil
 }
 
-// DecodeUntilMarker decodes NALUs from a RTP packet and puts them in a buffer.
-// When a packet has the marker flag (meaning that all the NALUs with the same PTS have
-// been received), the buffer is returned.
+// DecodeUntilMarker decodes an access unit from a RTP packet.
 func (d *Decoder) DecodeUntilMarker(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
-	nalus, pts, err := d.Decode(pkt)
+	nalus, pts, err := d.decodeNALUs(pkt)
 	if err != nil {
 		return nil, 0, err
 	}
diff --git a/pkg/formats/rtph264/decoder_test.go b/pkg/formats/rtph264/decoder_test.go
index f8136b84..c48ec544 100644
--- a/pkg/formats/rtph264/decoder_test.go
+++ b/pkg/formats/rtph264/decoder_test.go
@@ -21,7 +21,7 @@ func TestDecode(t *testing.T) {
 			for _, pkt := range ca.pkts {
 				clone := pkt.Clone()
 
-				addNALUs, _, err := d.Decode(pkt)
+				addNALUs, _, err := d.DecodeUntilMarker(pkt)
 
 				// test input integrity
 				require.Equal(t, clone, pkt)
@@ -44,10 +44,10 @@ func TestDecodeCorruptedFragment(t *testing.T) {
 	err := d.Init()
 	require.NoError(t, err)
 
-	_, _, err = d.Decode(&rtp.Packet{
+	_, _, err = d.DecodeUntilMarker(&rtp.Packet{
 		Header: rtp.Header{
 			Version:        2,
-			Marker:         false,
+			Marker:         true,
 			PayloadType:    96,
 			SequenceNumber: 17645,
 			Timestamp:      2289527317,
@@ -63,10 +63,10 @@ func TestDecodeCorruptedFragment(t *testing.T) {
 	})
 	require.Equal(t, ErrMorePacketsNeeded, err)
 
-	nalus, _, err := d.Decode(&rtp.Packet{
+	nalus, _, err := d.DecodeUntilMarker(&rtp.Packet{
 		Header: rtp.Header{
 			Version:        2,
-			Marker:         false,
+			Marker:         true,
 			PayloadType:    96,
 			SequenceNumber: 17646,
 			Timestamp:      2289527317,
@@ -100,7 +100,7 @@ func TestDecodeSTAPAWithPadding(t *testing.T) {
 		},
 	}
 
-	nalus, _, err := d.Decode(&pkt)
+	nalus, _, err := d.DecodeUntilMarker(&pkt)
 	require.NoError(t, err)
 	require.Equal(t, [][]byte{
 		{0xaa, 0xbb},
@@ -113,7 +113,7 @@ func TestDecodeAnnexB(t *testing.T) {
 	err := d.Init()
 	require.NoError(t, err)
 
-	nalus, _, err := d.Decode(&rtp.Packet{
+	nalus, _, err := d.DecodeUntilMarker(&rtp.Packet{
 		Header: rtp.Header{
 			Version:        2,
 			Marker:         true,
@@ -132,7 +132,7 @@ func TestDecodeAnnexB(t *testing.T) {
 	}, nalus)
 
 	for i := 0; i < 2; i++ {
-		nalus, _, err := d.Decode(&rtp.Packet{
+		nalus, _, err := d.DecodeUntilMarker(&rtp.Packet{
 			Header: rtp.Header{
 				Version:        2,
 				Marker:         true,
@@ -217,7 +217,7 @@ func FuzzDecoder(f *testing.F) {
 		d := &Decoder{}
 		d.Init() //nolint:errcheck
 
-		d.Decode(&rtp.Packet{ //nolint:errcheck
+		d.DecodeUntilMarker(&rtp.Packet{ //nolint:errcheck
 			Header: rtp.Header{
 				Version:        2,
 				Marker:         false,
@@ -229,7 +229,7 @@ func FuzzDecoder(f *testing.F) {
 			Payload: a,
 		})
 
-		d.Decode(&rtp.Packet{ //nolint:errcheck
+		d.DecodeUntilMarker(&rtp.Packet{ //nolint:errcheck
 			Header: rtp.Header{
 				Version:        2,
 				Marker:         false,
diff --git a/pkg/formats/rtph265/decoder.go b/pkg/formats/rtph265/decoder.go
index 40389781..508718f7 100644
--- a/pkg/formats/rtph265/decoder.go
+++ b/pkg/formats/rtph265/decoder.go
@@ -58,7 +58,13 @@ func (d *Decoder) Init() error {
 }
 
 // Decode decodes NALUs from a RTP packet.
+//
+// Deprecated: this method returns incomplete access units.
 func (d *Decoder) Decode(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
+	return d.decodeNALUs(pkt)
+}
+
+func (d *Decoder) decodeNALUs(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
 	if len(pkt.Payload) < 2 {
 		d.fragments = d.fragments[:0] // discard pending fragments
 		return nil, 0, fmt.Errorf("payload is too short")
@@ -161,11 +167,9 @@ func (d *Decoder) Decode(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
 	return nalus, d.timeDecoder.Decode(pkt.Timestamp), nil
 }
 
-// DecodeUntilMarker decodes NALUs from a RTP packet and puts them in a buffer.
-// When a packet has the marker flag (meaning that all the NALUs with the same PTS have
-// been received), the buffer is returned.
+// DecodeUntilMarker decodes an access unit from a RTP packet.
 func (d *Decoder) DecodeUntilMarker(pkt *rtp.Packet) ([][]byte, time.Duration, error) {
-	nalus, pts, err := d.Decode(pkt)
+	nalus, pts, err := d.decodeNALUs(pkt)
 	if err != nil {
 		return nil, 0, err
 	}
diff --git a/pkg/formats/rtph265/decoder_test.go b/pkg/formats/rtph265/decoder_test.go
index 200ac5a2..efd88d82 100644
--- a/pkg/formats/rtph265/decoder_test.go
+++ b/pkg/formats/rtph265/decoder_test.go
@@ -20,7 +20,7 @@ func TestDecode(t *testing.T) {
 			for _, pkt := range ca.pkts {
 				clone := pkt.Clone()
 
-				addNALUs, _, err := d.Decode(pkt)
+				addNALUs, _, err := d.DecodeUntilMarker(pkt)
 
 				// test input integrity
 				require.Equal(t, clone, pkt)
@@ -65,7 +65,7 @@ func FuzzDecoder(f *testing.F) {
 		d := &Decoder{}
 		d.Init() //nolint:errcheck
 
-		d.Decode(&rtp.Packet{ //nolint:errcheck
+		d.DecodeUntilMarker(&rtp.Packet{ //nolint:errcheck
 			Header: rtp.Header{
 				Version:        2,
 				Marker:         false,
@@ -77,7 +77,7 @@ func FuzzDecoder(f *testing.F) {
 			Payload: a,
 		})
 
-		d.Decode(&rtp.Packet{ //nolint:errcheck
+		d.DecodeUntilMarker(&rtp.Packet{ //nolint:errcheck
 			Header: rtp.Header{
 				Version:        2,
 				Marker:         false,