[gst-devel] media-info, and old streaminfo tags

[Benjamin Otte]

Quoting Martin Soto <soto at informatik.uni-kl.de>:

> Well, as I explained, I'm usually sending sound, so I really need and
> audio sink. It is just that every now and then there are passages
> without sound, and I have to handle them as well. My older player tries
> to modify the pipeline in such cases to disconnect the audio component,
> and believe me, doing that raises more issues than it solves. The main
> problem is that it is very hard to touch the pipeline without disrupting
> the data flow. You unlink a pad a bit too early, and you may prevent
> some important data from reaching its intended destination. This may
> result in all sorts of funny behavior, specially in DVD menus.
> 
I think the correct behaviour would be to send silence in that case. Or invent 
some sort of event to tell the stream there's nothing there. But just not 
sending anything doesn't work. (We've got to solve the same problem for MIDI 
btw)

> Well, I'm not speaking of design documents, but rather of
> specifications, and those are created and used very often by the free
> software community. Four examples out of my head:
> 
> - Python Enhancement Proposals (http://www.python.org/peps/)
> - Debian policy documents (http://www.debian.org/devel/)
> - The FreeDesktop standards (http://www.freedesktop.org/Standards/Home)
> - Gnome Enhancement Proposals (http://developer.gnome.org/gep/).
> 
> My point is that some areas of GStreamer need to be specified that way. 
> The beauty of GStreamer is that you can mix elements freely, but in
> practice, you end up very often with a non-working pipeline, because of
> small inconsistencies between the various components.
> 
The GEP looks like it never took off. Debian and FDO are more or less 
standards for interoperability between different software packages. And they 
take a long time. I'm not sure you want such a thing inside a single project.

> I agree, David did a great work with the caps negotiation subsystem. And
> one of the good things he did was putting together a text document
> explaining how the whole thing works. You certainly know what to expect
> of capsnego one you use it.
> 
If that's enough documentation for you, then I'm fine with writing that much 
myself for the stuff that I do. I don't consider those two files in 
docs/random more than an overview. 

> Reading the code works in many cases, but there are also situations in
> which some additional documentation comes handy. For example try to tell
> how schedulers work in GStreamer by reading the code from the opt
> scheduler. First, it will take you a fair amount of time and a lot of
> hair pulling to make yourself an idea of how it works. And second, at
> the end you will only know how opt works, because the other schedulers
> behave differently and you don't know where the differences are. I guess
> a concise text document telling you how schedulers are supposed to
> behave wouldn't be that bad, after all.
> 
I've been thinking about how much documentation we need and want quite a bit 
since this topic has come up.
I'd divide developers using GStreamer into three sections:
- application developers
Those guys need an API to plug their pipelines together that is well 
documented. If something doesn't work as expected, they file a bug and we take 
care of it.
examples: Ross, Colin
equivalent (in Gtk): app developers doing their app with Gtk. They use the API 
docs.
- plugin developers
Those guys need a deeper understanding of how GStreamer works internally. They 
need design overview documents (like the PWG) and an even bigger API reference 
for the plugin API. Depending on how hard their problem is, they might even 
need to look into code of other plugins or the core to figure out how that 
works.
examples: Christophe, Julien
equivalent: people writing their own widgets. I've had to read quite some code 
to get my fullscreen widget do correct focus handling...
- core developers
They implement the new stuff. They read the code of the core and know most of 
it inside out. Nonetheless they're happy to have some structural overview of 
subsystems if they need to get into it and weren't before.
examples: David, me
equivalent: gtk developers

All of those have quite the same documentation available as the Gtk peers. The 
difference in most cases is that in GStreamer the stuff doesn't work 
predictable while in Gtk it does. If your app would just disconnect the 
elements when you didn't need them you wouldn't have thought about clocking or 
scheduling at all.
You probably never thought about the way Gtk allocates space to its widgets 
and you probably don't care. Because it just works.

I'm not saying we're perfect. I'm just not thinking we're doing something 
terribly wrong wrt documentation.

Benjamin