Term list /glossary

[yara-blue]

Rodio has more contributors :tada: and the maintenance team is growing stronger :partying_face:. Communication and documentation efforts are harder then they have to be because we do not have words for every concept in rodio.

My goal is to build a glossary (specialized term list) and make that part of the documentation. We could make the docs link to that glossary each time one of its specialized terms is used.

It seems most urgent to get some words around the audio... pipelines?:

let thing = Decoder::new("path").amplify().pausable()

what do we call each of these steps and how they relate to each-other?

Lets give the steps names so we can discuss this more easily:

let decoder = Decoder::new();
let amplified = decoder.amplify();
let pausable = amplified.pausable();

This is an audio pipeline, but it could also be an audio tree (if we introduce mix). I think we need a words for

• the thing that generates the samples on one end of the pipeline/tree. Maybe it should be called the generator?
• referring to an earlier or later step in the pipeline/tree. Concretely is pausable, which is applied after amplify, the parent of amplify or its child? Maybe some other word works? And what is called the other way round?
• things that these pipelines are fed to. When this pipeline is consumed by something, what do we call it? consumer? It could also be called a Sink as that word will be freed up once we deprecate the Sink struct.

[yara-blue]

I notice myself referring to the later step in a pipeline as 'the source above it'. So that might work too. And I also sometimes call it the outer source.

[iluvcapra]

Something I found confusing when I was first working with the types was the use of the word "frame" in functions like Source::current_frame_len. I'm accustomed to a frame being a contiguous group of simultaneous samples, like a stereo 48k WAV file has 48000 audio frames per second, and each frame has two samples. This is the terminology used in CoreAudio, the python wave library, it seems pretty common.

rodio's sense of the word "frame" is more like what CoreAudio would call a "buffer" or ADM would call a "block", a contiguous array of frames from one read operation, or transaction, or whatever. It might help to clarify that.

[PetrGlad]

Yes, I thought of renaming "frame" methods as well. Replacing "frame" with "chunk", "run", or "span". But "chunk" usually refers to some small contained piece, and in rodio's use it can be even the whole track. And "run" is too overloaded. So maybe it can be a "span".

[iluvcapra]

Yes, I thought of renaming "frame" methods as well. Replacing "frame" with "chunk", "run", or "span". But "chunk" usually refers to some small contained piece, and in rodio's use it can be even the whole track. And "run" is too overloaded. So maybe it can be a "span".

What causes a break in frames currently?

1. An upstream source changing format.
2. An upstream source exhausting, end-of-file, something like that.
3. What else??

[PetrGlad]

We probably should not care what changes format, only need to delimit uniform and varying sources. Or do you have some completely different approach in mind other than providing number of samples before change?

[yara-blue]

So maybe it can be a "span".

yeah I do not mind this rename. Most rodio users do not seem to implement their own Source's so they should not be affected. We should very carefully document this and really get started on a porting guide since this can confuse ppl a lot :sweat_smile: .

[PetrGlad]

@iluvcapra Media containers may a series of pieces with differing encodings - those are external sources. Sample rate, channel count and scalar type of samples are parts of the format. But I do not have examples when this can be changed dynamically, unless maybe some filter that always tries to mimic its input may change format too. I am a big fan of conventions, so I'd prefer to use the same format in the processing chain (to the extent possible) and only do conversion at he edges (at external inputs and/or at final output).

[yara-blue]

It seems everyone here is on board with the follow changes right?

• rodio's frame will be renamed to span
• from now a frame is a contiguous group of simultaneous samples

[yara-blue]

Regarding the audio pipeline I have an idea, no idea if its good or bad. We could make a split into transforming sources (no idea what we would call those) and generating sources lets keep calling the Source. Methods like inner_mut() would become part of transforming sources.

[PetrGlad]

I was also wondering what a good word for the processing step would be. Calling function that converts inputs into outputs a "source" seems confusing to me. I'd called it "filter" but then there should be a word denoting any node in the pipeline, since mentioning "sources and filters" every time would be cumbersome.

[iluvcapra]

It seems everyone here is on board with the follow changes right?

• rodio's frame will be renamed to span

This is good to me. I'm still kinda confused about the contracts around "spans", like does a source HAVE to give prior warning for the end of a span, does a span HAVE to be a break in sample rate, channel count, etc. or can it just be client's choice?

• from now a frame is a contiguous group of simultaneous samples

This helps a lot I think.

I was also wondering what a good word for the processing step would be. Calling function that converts inputs into outputs a "source" seems confusing to me. I'd called it "filter" but then there should be a word denoting any node in the pipeline, since mentioning "sources and filters" every time would be cumbersome.

The way I've seen this done in other places is there's a Source interface, a Sink interface, and a type that implements both is a filter; types that implement just the former are generators, instruments, whatever; types that implement just the latter are outputs to the host audio system, write files, render visualizations...

[yara-blue]

does a source HAVE to give prior warning for the end of a span,

Yes, a span has a fixed length that must be known up front.

does a span HAVE to be a break in sample rate, channel count, etc. or can it just be client's choice?

It does not have to change but you are only allowed to change channel count or sample rate when starting a new span.