flac: Add API examples. Fixes #11.

cmd/flac-frame/flac-frame.go

@@ -1,58 +0,0 @@
-package main
-
-import (
-	"crypto/md5"
-	"flag"
-	"fmt"
-	"io"
-	"log"
-	"os"
-	"runtime/pprof"
-
-	"gopkg.in/mewkiz/flac.v1"
-)
-
-func main() {
-	f, err := os.Create("flac-frame.pprof")
-	if err != nil {
-		log.Println(err)
-	}
-	defer f.Close()
-	err = pprof.StartCPUProfile(f)
-	if err != nil {
-		log.Println(err)
-	}
-	defer pprof.StopCPUProfile()
-
-	flag.Parse()
-	for _, path := range flag.Args() {
-		err := flacFrame(path)
-		if err != nil {
-			log.Println(err)
-		}
-	}
-}
-
-func flacFrame(path string) error {
-	stream, err := flac.ParseFile(path)
-	if err != nil {
-		return err
-	}
-	defer stream.Close()
-
-	md5sum := md5.New()
-	for {
-		frame, err := stream.ParseNext()
-		if err != nil {
-			if err == io.EOF {
-				break
-			}
-			return err
-		}
-		frame.Hash(md5sum)
-	}
-	fmt.Printf("original MD5: %032x\n", stream.Info.MD5sum[:])
-	fmt.Printf("decoded MD5:  %032x\n", md5sum.Sum(nil))
-
-	return nil
-}

example_test.go

@@ -0,0 +1,121 @@
+package flac_test
+
+import (
+	"bytes"
+	"crypto/md5"
+	"fmt"
+	"io"
+	"log"
+
+	"gopkg.in/mewkiz/flac.v1"
+)
+
+func ExampleParseFile() {
+	// Parse metadata of love.flac
+	stream, err := flac.ParseFile("testdata/love.flac")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer stream.Close()
+
+	fmt.Printf("unencoded audio md5sum: %032x\n", stream.Info.MD5sum[:])
+	for i, block := range stream.Blocks {
+		fmt.Printf("block %d: %v\n", i, block.Type)
+	}
+	// Output:
+	// unencoded audio md5sum: bdf6f7d31f77cb696a02b2192d192a89
+	// block 0: seek table
+	// block 1: vorbis comment
+	// block 2: padding
+}
+
+func ExampleOpen() {
+	// Open love.flac for audio streaming without parsing metadata.
+	stream, err := flac.Open("testdata/love.flac")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer stream.Close()
+
+	// Parse audio samples and verify the MD5 signature of the decoded audio
+	// samples.
+	md5sum := md5.New()
+	for {
+		// Parse one frame of audio samples at the time, each frame containing one
+		// subframe per audio channel.
+		frame, err := stream.ParseNext()
+		if err != nil {
+			if err == io.EOF {
+				break
+			}
+			log.Fatal(err)
+		}
+		frame.Hash(md5sum)
+
+		// Print first three samples from each channel of the first five frames.
+		if frame.Num < 5 {
+			fmt.Printf("frame %d\n", frame.Num)
+			for i, subframe := range frame.Subframes {
+				fmt.Printf("  subframe %d\n", i)
+				for j, sample := range subframe.Samples {
+					if j >= 3 {
+						break
+					}
+					fmt.Printf("    sample %d: %v\n", j, sample)
+				}
+			}
+		}
+	}
+	fmt.Println()
+
+	got, want := md5sum.Sum(nil), stream.Info.MD5sum[:]
+	fmt.Println("decoded audio md5sum valid:", bytes.Equal(got, want))
+	// Output:
+	// frame 0
+	//   subframe 0
+	//     sample 0: 126
+	//     sample 1: 126
+	//     sample 2: 126
+	//   subframe 1
+	//     sample 0: 126
+	//     sample 1: 126
+	//     sample 2: 126
+	// frame 1
+	//   subframe 0
+	//     sample 0: 126
+	//     sample 1: 126
+	//     sample 2: 126
+	//   subframe 1
+	//     sample 0: 126
+	//     sample 1: 126
+	//     sample 2: 126
+	// frame 2
+	//   subframe 0
+	//     sample 0: 121
+	//     sample 1: 130
+	//     sample 2: 137
+	//   subframe 1
+	//     sample 0: 121
+	//     sample 1: 130
+	//     sample 2: 137
+	// frame 3
+	//   subframe 0
+	//     sample 0: -9501
+	//     sample 1: -6912
+	//     sample 2: -3916
+	//   subframe 1
+	//     sample 0: -9501
+	//     sample 1: -6912
+	//     sample 2: -3916
+	// frame 4
+	//   subframe 0
+	//     sample 0: 513
+	//     sample 1: 206
+	//     sample 2: 152
+	//   subframe 1
+	//     sample 0: 513
+	//     sample 1: 206
+	//     sample 2: 152
+	//
+	// decoded audio md5sum valid: true
+}

meta/meta.go

@@ -181,6 +181,27 @@ const (
 	TypePicture
 )
 
+func (t Type) String() string {
+	switch t {
+	case TypeStreamInfo:
+		return "stream info"
+	case TypePadding:
+		return "padding"
+	case TypeApplication:
+		return "application"
+	case TypeSeekTable:
+		return "seek table"
+	case TypeVorbisComment:
+		return "vorbis comment"
+	case TypeCueSheet:
+		return "cue sheet"
+	case TypePicture:
+		return "picture"
+	default:
+		return "<unknown block type>"
+	}
+}
+
 // unexpected returns io.ErrUnexpectedEOF if err is io.EOF, and returns err
 // otherwise.
 func unexpected(err error) error {