design: tweak Clip interface to separate seeking
Seeking within the audio source is not always a trivial problem, e.g.
the cases where the underlying source is encoded with a VBR
compression algorithm, optimistic seeking and slurping the entire
data source may be required.
Separation of the Seek method allows us to explain the requirements
from the implementors more easily. Since different encoders will have
different stragies to Seek, it is also easy to document the cost and
the underlying algorithm to the users.
Also, the seperation helps us document the requirements of
implementing an efficient Clip.Frames. We are explecting decoders
to have a cursor on the data source and move forward as new Frames
calls arrive. We only expect them to modify the cursor if seeking
is required. Without a separate Seek method, implementors need to
check if the offset is matching with their current internal cursor
and seek if it is not. Separation saves them figuring out the
conditional case for a requirement of seeking.
Change-Id: I0b15d56df9457a462953aaaf915445e268462f97
Reviewed-on: https://go-review.googlesource.com/24702
Reviewed-by: David Crawshaw <crawshaw@golang.org>
diff --git a/design/13432-mobile-audio.md b/design/13432-mobile-audio.md
index d93272d..cd7c386 100644
--- a/design/13432-mobile-audio.md
+++ b/design/13432-mobile-audio.md
@@ -148,10 +148,16 @@
//
// FrameInfo returns the basic frame information about the clip audio.
//
+// Seek seeks (offset*framesize*channels) byte in the source audio data.
+// Seeking to negative offsets are illegal.
+// An error is returned if the offset is out of the bounds of the
+// audio data source.
+//
// Size returns the total number of bytes of the underlying audio data.
// TODO(jbd): Support cases where size is unknown?
type Clip interface {
- Frames(buf []byte, offset int64) (n int, err error)
+ Frames(buf []byte) (n int, err error)
+ Seek(offset int64) (error)
FrameInfo() FrameInfo
Size() int64
}
