From 373dc625f82b47096893add42c4472e4a57ab7eb Mon Sep 17 00:00:00 2001 From: Aki Date: Wed, 9 Feb 2022 22:23:03 +0100 Subject: Moved third-party libraries to a separate subdirectory --- vorbis/doc/vorbis-clip.txt | 139 --------------------------------------------- 1 file changed, 139 deletions(-) delete mode 100644 vorbis/doc/vorbis-clip.txt (limited to 'vorbis/doc/vorbis-clip.txt') diff --git a/vorbis/doc/vorbis-clip.txt b/vorbis/doc/vorbis-clip.txt deleted file mode 100644 index 2e67034..0000000 --- a/vorbis/doc/vorbis-clip.txt +++ /dev/null @@ -1,139 +0,0 @@ -Topic: - -Sample granularity editing of a Vorbis file; inferred arbitrary sample -length starting offsets / PCM stream lengths - -Overview: - -Vorbis, like mp3, is a frame-based* audio compression where audio is -broken up into discrete short time segments. These segments are -'atomic' that is, one must recover the entire short time segment from -the frame packet; there's no way to recover only a part of the PCM time -segment from part of the coded packet without expanding the entire -packet and then discarding a portion of the resulting PCM audio. - -* In mp3, the data segment representing a given time period is called - a 'frame'; the roughly equivalent Vorbis construct is a 'packet'. - -Thus, when we edit a Vorbis stream, the finest physical editing -granularity is on these packet boundaries (the mp3 case is -actually somewhat more complex and mp3 editing is more complicated -than just snipping on a frame boundary because time data can be spread -backward or forward over frames. In Vorbis, packets are all -stand-alone). Thus, at the physical packet level, Vorbis is still -limited to streams that contain an integral number of packets. - -However, Vorbis streams may still exactly represent and be edited to a -PCM stream of arbitrary length and starting offset without padding the -beginning or end of the decoded stream or requiring that the desired -edit points be packet aligned. Vorbis makes use of Ogg stream -framing, and this framing provides time-stamping data, called a -'granule position'; our starting offset and finished stream length may -be inferred from correct usage of the granule position data. - -Time stamping mechanism: - -Vorbis packets are bundled into into Ogg pages (note that pages do not -necessarily contain integral numbers of packets, but that isn't -inportant in this discussion. More about Ogg framing can be found in -ogg/doc/framing.html). Each page that contains a packet boundary is -stamped with the absolute sample-granularity offset of the data, that -is, 'complete samples-to-date' up to the last completed packet of that -page. (The same mechanism is used for eg, video, where the number -represents complete 2-D frames, and so on). - -(It's possible but rare for a packet to span more than two pages such -that page[s] in the middle have no packet boundary; these packets have -a granule position of '-1'.) - -This granule position mechaism in Ogg is used by Vorbis to indicate when the -PCM data intended to be represented in a Vorbis segment begins a -number of samples into the data represented by the first packet[s] -and/or ends before the physical PCM data represented in the last -packet[s]. - -File length a non-integral number of frames: - -A file to be encoded in Vorbis will probably not encode into an -integral number of packets; such a file is encoded with the last -packet containing 'extra'* samples. These samples are not padding; they -will be discarded in decode. - -*(For best results, the encoder should use extra samples that preserve -the character of the last frame. Simply setting them to zero will -introduce a 'cliff' that's hard to encode, resulting in spread-frame -noise. Libvorbis extrapolates the last frame past the end of data to -produce the extra samples. Even simply duplicating the last value is -better than clamping the signal to zero). - -The encoder indicates to the decoder that the file is actually shorter -than all of the samples ('original' + 'extra') by setting the granule -position in the last page to a short value, that is, the last -timestamp is the original length of the file discarding extra samples. -The decoder will see that the number of samples it has decoded in the -last page is too many; it is 'original' + 'extra', where the -granulepos says that through the last packet we only have 'original' -number of samples. The decoder then ignores the 'extra' samples. -This behavior is to occur only when the end-of-stream bit is set in -the page (indicating last page of the logical stream). - -Note that it not legal for the granule position of the last page to -indicate that there are more samples in the file than actually exist, -however, implementations should handle such an illegal file gracefully -in the interests of robust programming. - -Beginning point not on integral packet boundary: - -It is possible that we will the PCM data represented by a Vorbis -stream to begin at a position later than where the decoded PCM data -really begins after an integral packet boundary, a situation analagous -to the above description where the PCM data does not end at an -integral packet boundary. The easiest example is taking a clip out of -a larger Vorbis stream, and choosing a beginning point of the clip -that is not on a packet boundary; we need to ignore a few samples to -get the desired beginning point. - -The process of marking the desired beginning point is similar to -marking an arbitrary ending point. If the encoder wishes sample zero -to be some location past the actual beginning of data, it associates a -'short' granule position value with the completion of the second* -audio packet. The granule position is associated with the second -packet simply by making sure the second packet completes its page. - -*(We associate the short value with the second packet for two reasons. - a) The first packet only primes the overlap/add buffer. No data is - returned before decoding the second packet; this places the decision - information at the point of decision. b) Placing the short value on - the first packet would make the value negative (as the first packet - normally represents position zero); a negative value would break the - requirement that granule positions increase; the headers have - position values of zero) - -The decoder sees that on the first page that will return -data from the overlap/add queue, we have more samples than the granule -position accounts for, and discards the 'surplus' from the beginning -of the queue. - -Note that short granule values (indicating less than the actually -returned about of data) are not legal in the Vorbis spec outside of -indicating beginning and ending sample positions. However, decoders -should, at minimum, tolerate inadvertant short values elsewhere in the -stream (just as they should tolerate out-of-order/non-increasing -granulepos values, although this too is illegal). - -Beginning point at arbitrary positive timestamp (no 'zero' sample): - -It's also possible that the granule position of the first page of an -audio stream is a 'long value', that is, a value larger than the -amount of PCM audio decoded. This implies only that we are starting -playback at some point into the logical stream, a potentially common -occurence in streaming applications where the decoder may be -connecting into a live stream. The decoder should not treat the long -value specially. - -A long value elsewhere in the stream would normally occur only when a -page is lost or out of sequence, as indicated by the page's sequence -number. A long value under any other situation is not legal, however -a decoder should tolerate both possibilities. - - -- cgit v1.1