Unexport Frame, update readme and example

Author: davidae

README.md

@@ -1,6 +1,8 @@
 # audiostream
+[![GoDoc](https://godoc.org/github.com/davidae/audiostream?status.svg)](https://godoc.org/github.com/davidae/audiostream)
+
 audiostream is a simple streaming API for audio files. It can easily be used 
-together with a HTTP server to stream audio.
+together with a HTTP server to stream audio to a HTTP client.
 
 This is package is used in an ongoing effort together with another private project. 
 
@@ -10,8 +12,8 @@ This is package is used in an ongoing effort together with another private proje
 * It will broadcast the files to any listeners in frames of bytes and the listeners can be read as a stream via channels.
 
 ## What does the API _not_ do?
-* It does not implement the SHOUTcast_ or _Icecast_ protocol.
-* It cannot decode or convert audio files. A decoder package can solve this and _ffmpeg_ can deal with converting sample rates if needed.
+* It does not implement the _SHOUTcast_ or _Icecast_ protocol.
+* It cannot decode, convert or manipulate audio files. Its up to the implementor to deal with this. A [decoder package](https://github.com/hajimehoshi/go-mp3) can solve this and _ffmpeg_ can deal with converting sample rates if needed.
 
 # Example
 See how to use the audiostream together with an HTTP server in [examples/main.go](https://github.com/davidae/audiostream/blob/master/example/main.go)
@@ -28,8 +30,7 @@ import (
 )
 
 func main() {
-	lazyFileRead := audiostream.WithFramzeSize(2)
-	stream := audiostream.NewStream(lazyFileRead)
+	stream := audiostream.NewStream(audiostream.WithFramzeSize(2))
 
 	stream.AppendAudio(&audiostream.Audio{
 		Data:       strings.NewReader("thisIsForSureNotAProperAudioFileThough"),
@@ -59,4 +60,4 @@ func main() {
 * https://stackoverflow.com/questions/35102278/python-3-get-song-name-from-internet-radio-stream
 * https://github.com/krotik/dudeldu
 * https://gist.github.com/jucrouzet/3e59877c0b4352966e6220034f2b84ac
-* https://stackoverflow.com/a/57634692
+* https://stackoverflow.com/a/57634692

example/main.go

@@ -23,7 +23,7 @@ func main() {
 		Artist:     "Fizz",
 		Title:      "Buzz",
 		Filename:   "your-mp3-file.mp3",
-		SampleRate: 44100,
+		SampleRate: 44100, // a naive assumption, use a decoder to know for sure.
 	})
 
 	http.HandleFunc("/audio", func(w http.ResponseWriter, r *http.Request) {
@@ -46,7 +46,7 @@ func main() {
 		for !endLoop {
 			select {
 			case <-time.After(time.Second * 2):
-				// client timed out
+				// timeout
 				endLoop = true
 			case out := <-listener.Stream():
 				binary.Write(w, binary.BigEndian, out)
@@ -66,4 +66,5 @@ func main() {
 	http.ListenAndServe(":8080", nil)
 }
 
+// To easily listen in,
 // mplayer http://localhost:8080/audio -v

listener.go

@@ -4,9 +4,10 @@ import (
 	"github.com/gofrs/uuid"
 )
 
+// Listener is a client used to listen to the stream of audio
 type Listener struct {
 	uuid             string
-	frame            chan Frame
+	frame            chan frame
 	stream           chan []byte
 	startedToStream  bool
 	metadataInterval int64
@@ -36,7 +37,7 @@ func NewListener(opts ...ListenerOption) (*Listener, error) {
 	l := &Listener{
 		uuid:   uuid.String(),
 		stream: make(chan []byte),
-		frame:  make(chan Frame),
+		frame:  make(chan frame),
 	}
 
 	for _, o := range opts {

stream.go

@@ -10,7 +10,6 @@ import (
 )
 
 const (
-	defaultListenerTimeout  = time.Millisecond * 500
 	defaultFrameSize        = 3000
 	defaultMetadataInterval = 65536
 
@@ -29,7 +28,8 @@ var (
 // StreamOption is a func used to configure the streamer upon initialization
 type StreamOption func(s *Stream)
 
-// WithFramzeSize sets the frame size, which if the size of bytes used when reading a block of audio
+// WithFramzeSize sets the frame size, which if the size of bytes used when reading a block of audio.
+// The default frame size is 3000
 func WithFramzeSize(size int) StreamOption {
 	return func(s *Stream) { s.frameSize = size }
 }
@@ -45,8 +45,9 @@ func DefaultSleepForFunc() SleepFor {
 }
 
 // WithLazyFileRead is an option that will halt the stream from reading an audio file overzealously and
-// passing it on to the listeners. This can be useful if we want to keep the in-memory low and
-// avoid often empty queueus
+// passing it on to the listeners. This can be useful if we want to keep the in-memory low,
+// provide a "now playing" functionality without using the `ICY protocol` (be in sync with what the client is reading),
+// avoid overflowing the buffer reading the stream (f.ex. an HTTP client) and avoid often empty queues
 func WithLazyFileRead(fn SleepFor) StreamOption {
 	return func(s *Stream) {
 		s.lazyFileReading = true
@@ -65,15 +66,15 @@ type Audio struct {
 // Read will read the audio data
 func (a *Audio) Read(b []byte) (int, error) { return a.Data.Read(b) }
 
-// Frame is a simple abstraction of what a stream will send to its listeners
-type Frame struct {
+// frame is a simple abstraction of what a stream will send to its listeners
+type frame struct {
 	data          []byte
 	title, artist string
 }
 
 // ShoutcastMetadata will build a frame to send metadata to a client that can
 // decode/parse ShoutCast metadata as a part of the audio stream from a listener
-func (f Frame) ShoutcastMetadata() []byte {
+func (f frame) ShoutcastMetadata() []byte {
 	meta := fmt.Sprintf("StreamTitle='%v - %v';", f.artist, f.title)
 
 	// is it above max size?
@@ -188,8 +189,8 @@ func (s *Stream) Start() error {
 		}
 
 		// read a frame from audio
-		frame := make([]byte, s.frameSize)
-		bytes, err := s.reading.Read(frame)
+		dataFrame := make([]byte, s.frameSize)
+		bytes, err := s.reading.Read(dataFrame)
 		if err != nil {
 			// we are done reading this audio file
 			if err == io.EOF {
@@ -210,7 +211,7 @@ func (s *Stream) Start() error {
 		wg.Add(len(s.listeners))
 		for _, l := range s.listeners {
 			go func(l *Listener) {
-				l.frame <- Frame{data: frame, artist: s.reading.Artist, title: s.reading.Title}
+				l.frame <- frame{data: dataFrame, artist: s.reading.Artist, title: s.reading.Title}
 				wg.Done()
 			}(l)
 		}