Re: Response to your LC Comment -2419 on Media API spec

Dear MAWG,

On Sep 29, 2010, at 09:12 , Thierry MICHEL wrote:
> 4 comments are not done yet (for 2 of them we need to contact other WG's, the other 2 require changes to the ontology document).

Thanks! I would kindly request that you ping me again when these four comments are resolved so that we may ensure alignment. For any response not listed here please consider it assented to.

> substantial: "Example on how to introduce this in HTML5 by making the HTMLMediaElement inherit from the MediaResource interface:" This shouldn't be an example. If a user agent is expected to expose this interface on media elements, then this has to be a MUST, possibly using an "implements" statement.
> [MA] We will coordinate with the HTML WG on this issue.

I am not certain that you need to coordinate with the HTML WG. This is mostly a Web IDL and testability issue. First, this can't be an example as it is a normative requirement on browsers. You therefore need a statement of the order "User agents that support [HTML5] MUST expose the MediaResource interface on objects that implement HTMLMediaElement." This can be further captured in Web IDL with the simple statement:

  HTMLMediaElement implements MediaResource;

> substantial: The general getProperty/getDiagnosis architecture seems skewed. I wonder if the API does not do more than what is actually required. I presume that when a getProperty request is made, all the metadata has already been loaded in memory and is available for immediate retrieval.
> [MA] We include the possibility that the media resource and metadata are stored externally and not yet loaded in memory.

OK.

> If that is not the case, the API *really* needs to be made asynchronous, otherwise it won't be usable in a browser context at all (or in any kind of performance-conscious environment, such as typically a web server).
> [MA] We have added an asynchronous version of the getMediaProperty method as is used in the Geolocation API (http://dev.w3.org/geo/api/spec-source.html#geolocation).

It was a mistake in XMLHttpRequest to include both synchronous and asynchronous variants for general consumption — it leads to bad practices, which we should be discouraging by design. What the rest of the Web JS API stack is doing now is to have asynchronous APIs in the regular browser context, and (optionally) synchronous variant only available to Web Workers. See for instance the multiple File APIs. I suggest that you either go full asynchronous, or likewise make the synchronous variant workers-only.

Is there an updated draft where I can review the changes?

> If it is the case, then instead of specifying a complex filter in getProperty's parameters, it would be a lot simpler to just expose the property and leave it up to code to do the filtering. So instead of
> 
> props = mr.getProperty("title");
> props = mr.getProperty("title", "#subchapter");
> props = mr.getProperty("title", null, "tva");
> props = mr.getProperty("title", null, null, null, "fr");
> 
> you would just have
> 
> props = mr.title;
> 
> and leave it up to code to perform any kind of filtering on its own terms. This can then be abstracted into a library. It seems clearer, and much more idiomatic.
> [MA] In fact, when none of the filters are included in the getMediaProperty parameters, the result array will hold all values. So if wanted the code can allways call the property without specifying the filters and do the filtering by itself.

That does not address the idiomaticity issues — I would need to see the new draft to see if the asynchronous variant improves that.

> substantial: getDiagnosis doesn't seem thread-safe, and I'm guessing that even in a JS context it could easily hit race conditions. Is conveying the exact reason why something was null really a strong use case in JS? If so, wouldn't an exception work? If not (which is what I suspect) this could be dropped. I doubt anyone would use it — in fact your examples never do!
> [MA] getDiagnosis has been dropped. The synchronous version of getMediaProperty now returs the status code directly, the asynchronous version calls an error callback method upon failure.

I'm satisfied with this resolution.

> substantial: I suggest exposing the properties directly on the object and removing getPropertyNamesWithValues.
> [MA] We have changed the "getPropertyNamesWithValues" to "getPropertyNamesHavingValues".

I'm sorry, can you please clarify how this addresses my concern?

> ed.: "MAObject" is not a very descriptive name, 75% of it is dedicated to saying that it's an object, which one already knows from the fact that it has been retrieved as such. "MediaAnnotation" would be clearer.
> [MA] Agreed.

Has the change been accepted?

> substantial: Would it not be simpler to replace getSourceFormatsWithValues with a sourceFormats array that could be filtered in code if one so desires? Is it even an important use case in the browser to list which metadata formats are available in general?
> [MA] getSourceFormatsWithValues has been dropped due to not finding a relevant use case.

I am satisfied with this resolution.

> substantial: I'm sorry but I don't understand what selectMAResource is supposed to do. Does it allow one to change the underlying resource which the current object is describing and load another one? If so, it should be asynchronous (and it should also be on another interface). What does the boolean which it returns mean? Or maybe it's loading additional external metadata? Again, if so, it really needs to be asynchronous (and probably somewhere else too).
> [MA] "selectMAResource" has been dropped in favor of a constructor. As such, if a MediaResource object is constructed it is connected to one media resource (identified in the constructor method). Changing the underlying resource is not possible anymore.
> For the other methods that operate on the MediaResource objects we have provided asynchronous versions. The constructor is synchronous and allows to identify the media resource and metadata sources.

I am satisfied with this resolution.

> ed.: It's probably worth indicating that the Language interface is meant to be inherited from, that it doesn't do much on its own.
> [MA] We have changed the name to MediaAnnotationLanguage and added information like you suggested.

I am satisfied with this resolution.

> substantial: It is not clear "plain text" is for unstructuredValue. Is this the raw binary for binary formats? A piece of XML for XML formats?
> [MA] The unstructuredValue holds the original metadata represented as a string. This can hold binary values from binary formats, XML elements, or anything else. The actual syntax is not defined and can be implementation dependent.

I would strongly suggest that you reference https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/TypedArray-spec.html for this (as for instance http://dev.w3.org/2009/dap/file-system/file-writer.html does). Arbitrary data is not really well captured by strings.

> substantial: What is the syntax of sourceFormat? Of mappingType? Of fragmentIdentifier?
> [MA] We have added information on the syntax. The sourceFormat should use the metadata format identifiers defined in the Ontology for Media Resources 1.0 specification.
> The value of the mappingType should be one of the mapping characteristics defined in Ontology for Media Resources 1.0 specification. The fragmentIdentifier should be an URI.

OK.

> substantial: Why is there a value field on Identifier if it's holding a URI that could be in the uri field it inherits from MAObject? Same for Locator, Creator.
> [MA] The uri attribute has been removed from the MediaAnnotation interface (formerly MAObject interface).

OK.

> substantial: The "usage as a service" segments aren't precise enough and normative enough to describe a protocol properly. I think that this document should limit itself to describing an API using WebIDL, and then either help define a REST binding for WebIDL or another document should be created for the protocol.
> [MA] We have moved the "usage as a service" segments to the usage examples section and mentioned that no Web IDL binding exists today for such services.

That seems fine. I encourage interested parties in MAWG to collaborate with DAP on this issue, if there's interest.

> substantial: It is quite counter-intuitive to have:
> 
> var lang = foo.getProperty("language").value;
> 
> when one could equally have:
> 
> var lang = foo.language;
> 
> The same applies to other properties, such as description.
> [MA] We consider the fact that requesting for one property can result in several results, depending on sub types, source formats, languages and fragments.
> Additionally, the different properties typically have different structure (e.g., language versus rating). We agreed on using only one method to access these properties, consequently
> the different results need to implement the same interface, hence the "value" attribute.

I am not entirely happy with this design but I guess that it can be wrapped in a library.

> substantial: The section CreateDate has just "Date" in the interface name. It should probably be "CreationDate" in both.
> [MA] We changed "Date" interface to "CreateDate" interface.

Shouldn't that be CreationDate?

> substantial: Your Location interface seems to overlap with equivalent interfaces defined by the Geolocation WG. I strongly recommend that you coordinate with them to return a similar interface.
> [MA] TODO We have contacted the Geolocation WG on establishing a connection.

OK, good.

> substantial: In general it would be a lot easier to read if interface attributes linked to the definition of the property in the ontology — especially if it is supposed to have a specific syntax. I didn't review each interface in great detail because going back and forth between the two documents to check that they were properly related was too tedious.
> [MA] TODO We have added links to the definition of the properties in the Ontology for Media Resources 1.0 specification. (Note that the links need to be updated in the ontology document).

That would be really helpful, thanks.

> substantial: It's unclear what to return for Compression. Is JPEG a compression? Something more specific? Is it case sensitive? Partially controlled?
> [MA] TODO This issue will be tackled in the ontology document.

OK, please inform me of the resolution when it is ready.

> substantial: The relationship of section 5 to HTTP is unclear. Is this needed?
> [MA] Some of the status codes were re-used from HTTP. This section merely elaborates on the status codes and presents the system specific ones.

It would be worth to indicate that this reuse is (presumably) just to pick something that developers are familiar with, and does not imply any specific link with HTTP.

> substantial: Section 7 should be beefed up. Notably, if I can access geographic information it could be used to access someone's location without them agreeing to it. Likewise for name and a number of other things. In general, you probably need to think about privacy.
> [MA] We have added a paragraph on this.

Can I please see the paragraph? I would like the privacy experts in DAP to look over it.

> note: integration with DAP's Media Capture is likely desirable.
> [MA] TODO Communication with the Media Capture WG has been initialized.

I think you mean DAP, but good!

-- 
Robin Berjon - http://berjon.com/

Received on Wednesday, 29 September 2010 08:44:17 UTC