opus - Oct 2015 - How to wrap Opus data in an Ogg stream?

Hi.
I am trying to understand how to package opus-encoded data in an ogg stream to
make a standards-compilant ogg/opus file. Most things are clear, but there is
one thing I simply do not understand.

What I do understand is that Ogg is based on pages, that each come with a fairly
sizeable header (>=27 bytes). Now, I encode with a fairly low bitrate, so my
opus packages are <100 bytes long. Therefore, it does not make sense to place
one Opus packet in each Ogg page because of the overhead.

Now, the following document (It has expired? Is it still valid?)
https://tools.ietf.org/html/draft-terriberry-oggopus-01
contains the following text regarding how to place Opus audio data in an Ogg
page ( =? Ogg packet ): "The first N-1 Opus packets, if any, are packed one
after another into the Ogg packet, using the self-delimiting framing from
Appendix B of  [RFCOpus]."

Reading said appendix, it seems that this self-delimiting format is not just
taking on a header to a regular packet, but somehow placing the packet length
inside the packet. Is this something I have to do manually, or is there a way to
tell libOpus to create these self-delimiting packets?
If I have to do it myself, is there a reference example somewhere I could look
at?

Sincerely
Daniel Armyr
Beginner Opus user.

On Wed, Oct 14, 2015 at 4:18 AM, Daniel Armyr <daniel at armyr.se>
wrote:
> Hi.
> I am trying to understand how to package opus-encoded data in an ogg stream
to make a standards-compilant ogg/opus file. Most things are clear, but there is
one thing I simply do not understand.
>
> What I do understand is that Ogg is based on pages, that each come with a
fairly sizeable header (>=27 bytes). Now, I encode with a fairly low bitrate,
so my opus packages are <100 bytes long. Therefore, it does not make sense to
place one Opus packet in each Ogg page because of the overhead.
If latency is not important, you will probably want one second of
audio or more per Ogg page.
>
> Now, the following document (It has expired? Is it still valid?)
https://tools.ietf.org/html/draft-terriberry-oggopus-01
It is now an IETF document.  The current version is:
https://tools.ietf.org/html/draft-ietf-codec-oggopus
> contains the following text regarding how to place Opus audio data in an
Ogg page ( =? Ogg packet ): "The first N-1 Opus packets, if any, are packed
one after another into the Ogg packet, using the self-delimiting framing from
Appendix B of  [RFCOpus]."
This is discussing how to combine multiple Opus packets (one for each
Opus stream) into a multi-stream Ogg Opus packet, for example if you
are encoding 5.1 channel surround sound.  For mono or stereo you would
only have one Opus packet in each Ogg Opus packet and would have no
need for self-delimited framing.

To put multiple Ogg Opus packets in an Ogg page, all you need to do is
start a new segment for each Ogg Opus packet.  There can be up to 255
segments per page.  For details, see the Ogg specification:
https://tools.ietf.org/html/rfc3533
>
> Reading said appendix, it seems that this self-delimiting format is not
just taking on a header to a regular packet, but somehow placing the packet
length inside the packet. Is this something I have to do manually, or is there a
way to tell libOpus to create these self-delimiting packets?
The libopus multi-stream API does this automatically when you are
using multiple streams.  It is not applicable with just one stream.

 - Mark

Thanks for a very quick and very good answer. Let me just double-check one
thing:
> To put multiple Ogg Opus packets in an Ogg page, all you need to do is
> start a new segment for each Ogg Opus packet.  There can be up to 255
> segments per page.  For details, see the Ogg specification:
> https://tools.ietf.org/html/rfc3533
So do I understand it correctly that a decoder will interpret a page that
contains multiple segments, each less than 255 bytes as a set of opus packages,
each with the length determined by the specified segment length?

And just to be absolutely certain: If I happen to have opus packets that are
more than 255 bytes long, will a decoder stitch together any segment that is of
length 255 with whatever comes next and then decode this as a single opus
packet?