convert Tracks into Medias and Formats (#155)

* split tracks from medias

* move tracks into dedicated package

* move media into dedicated package

* edit Medias.Marshal() in order to return SDP

* add medias.Find() and simplify examples

* improve coverage

* fix rebase errors

* replace TrackIDs with MediaIDs

* implement media-specific and track-specific callbacks for reading RTCP and RTP packets

* rename publish into record, read into play

* add v2 tag

* rename tracks into formats

examples/client-read-format-h264-convert-to-jpeg/main.go

@@ -0,0 +1,141 @@
+package main
+
+import (
+	"image"
+	"image/jpeg"
+	"log"
+	"os"
+	"strconv"
+	"time"
+
+	"github.com/aler9/gortsplib/v2"
+	"github.com/aler9/gortsplib/v2/pkg/format"
+	"github.com/aler9/gortsplib/v2/pkg/url"
+	"github.com/pion/rtp"
+)
+
+// This example shows how to
+// 1. connect to a RTSP server
+// 2. check if there's a H264 media
+// 3. decode H264 into RGBA frames
+// 4. encode the frames into JPEG images and save them on disk
+
+// This example requires the ffmpeg libraries, that can be installed in this way:
+// apt install -y libavformat-dev libswscale-dev gcc pkg-config
+
+func saveToFile(img image.Image) error {
+	// create file
+	fname := strconv.FormatInt(time.Now().UnixNano()/int64(time.Millisecond), 10) + ".jpg"
+	f, err := os.Create(fname)
+	if err != nil {
+		panic(err)
+	}
+	defer f.Close()
+
+	log.Println("saving", fname)
+
+	// convert to jpeg
+	return jpeg.Encode(f, img, &jpeg.Options{
+		Quality: 60,
+	})
+}
+
+func main() {
+	c := gortsplib.Client{}
+
+	// parse URL
+	u, err := url.Parse("rtsp://localhost:8554/mystream")
+	if err != nil {
+		panic(err)
+	}
+
+	// connect to the server
+	err = c.Start(u.Scheme, u.Host)
+	if err != nil {
+		panic(err)
+	}
+	defer c.Close()
+
+	// find published medias
+	medias, baseURL, _, err := c.Describe(u)
+	if err != nil {
+		panic(err)
+	}
+
+	// find the H264 media and format
+	var trak *format.H264
+	medi := medias.Find(&trak)
+	if medi == nil {
+		panic("media not found")
+	}
+
+	// setup RTP/H264->H264 decoder
+	rtpDec := trak.CreateDecoder()
+
+	// setup H264->raw frames decoder
+	h264RawDec, err := newH264Decoder()
+	if err != nil {
+		panic(err)
+	}
+	defer h264RawDec.close()
+
+	// if SPS and PPS are present into the SDP, send them to the decoder
+	sps := trak.SafeSPS()
+	if sps != nil {
+		h264RawDec.decode(sps)
+	}
+	pps := trak.SafePPS()
+	if pps != nil {
+		h264RawDec.decode(pps)
+	}
+
+	// setup the chosen media only
+	_, err = c.Setup(medi, baseURL, 0, 0)
+	if err != nil {
+		panic(err)
+	}
+
+	// called when a RTP packet arrives
+	saveCount := 0
+	c.OnPacketRTP(medi, trak, func(pkt *rtp.Packet) {
+		// convert RTP packets into NALUs
+		nalus, _, err := rtpDec.Decode(pkt)
+		if err != nil {
+			return
+		}
+
+		for _, nalu := range nalus {
+			// convert NALUs into RGBA frames
+			img, err := h264RawDec.decode(nalu)
+			if err != nil {
+				panic(err)
+			}
+
+			// wait for a frame
+			if img == nil {
+				continue
+			}
+
+			// convert frame to JPEG and save to file
+			err = saveToFile(img)
+			if err != nil {
+				panic(err)
+			}
+
+			saveCount++
+			if saveCount == 5 {
+				log.Printf("saved 5 images, exiting")
+				os.Exit(1)
+			}
+		}
+	})
+
+	// start playing
+	_, err = c.Play(nil)
+	if err != nil {
+		panic(err)
+	}
+
+	// wait until a fatal error
+	panic(c.Wait())
+}