Response to your LC Comment -2419 on Media API spec

Dear Robin,

The Media Annotations Working Group has reviewed the comments you sent 
[1] on the Last Call Working Draft [2] of the API for Media Resource 1.0 
published on 08 June 2010.
Thank you for having taken the time to review the document and to send 
us comments.

The Working Group's response to your comment is included below.
Please review it carefully and *let us know by email at 
public-media-annotation@w3.org if you agree with it or not*
before [09-Oct-2010].
In case of disagreement, you are requested to provide a specific 
solution for or a path to a consensus with the Working Group.
If such a consensus cannot be achieved, you will be given the 
opportunity to raise a formal objection which will then be reviewed by 
the Director during the transition of this document to the next stage in 
the W3C Recommendation Track.

Thanks,

For the Media Annotations Working Group,
Thierry Michel,
W3C Team Contact

1. 
http://lists.w3.org/Archives/Public/public-media-annotation/2010Aug/0017.html
2. http://www.w3.org/TR/2010/WD-mediaont-api-1.0-20100608

-----------------------
Resolution of the MAWG:
-----------------------


Response to the comments, we have copied your comments and added our 
answers to each of them inline ([MA]).
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).
----------------------------------------------------------------------

I just noticed something, shouldn't it be API for Media Resource*s*? 
Same comment for the Ontology document.
[MA] Agreed.

Here are my notes on [0]:

ed.: "Thereby, the Media Ontology Core Properties will be used as a 
pivot vocabulary in the API." I don't think that the "thereby" is needed 
here. (same thing further down)
[MA] Removed "Thereby".

ed.: "the metadata formats in scope (1.2 Formats in scope) are stored in 
the Media Ontology in order to provide cross-community data integration" 
Instead of "are stored in the Media Ontology" I think you mean "are 
documented in the Ontology for Media Resources specification", no?
[MA] Agreed.

ed.: "The JavaScript examples in this document will only work if the API 
is implemented by the browser." That's probably not true, you could have 
an implementation of the API running in Javascript outside the browser. 
You might wish to say instead something like "The examples provided in 
this specification use Javascript, but they ought to be simple to 
translate to another language if there binding is implemented there."
[MA] Agreed.

ed.: "The API exists of a number of interfaces" -> The API has a number 
of interfaces
[MA] Agreed.

ed.: "Implementations of the API should provide objects implementing the 
different interfaces." That's not clear, I would expect that 
implementations MUST support these interfaces. How those are made 
available as objects ought to be clear from the WebIDL.
[MA] Agreed.

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.

ed.: in getDiagnosis, "See Section 4" links to section 5.
[MA] Updated the link.

substantial: Parameters that are optional in WebIDL need to be marked as 
"optional" instead of using the OPTIONAL 2119 keyword in the prose.
[MA] Agreed.

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.

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).

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.

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.

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

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.

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.

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.


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.

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.

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.

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).

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.

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.

substantial: "For the latter a number of suggested terms are defined". 
If there is to be a controlled vocabulary, it needs to be in the 
ontology, not in the API. And "suggested" isn't really good, it's a 
MUST, a SHOULD, etc.
[MA] We have removed the "suggested terms" from this document.

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.

substantial: Why is it "createdate" in getProperty and createDate in the 
service URI? Are all those property names the local names from the 
ontology? I can't see that defined anywhere.
[MA] This is an error in the example and is updated. The property names 
are the local names from the ontology.

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.

substantial: (In Relation) "For the latter a number of suggested terms 
are defined:" but no list follows. And the same comments apply as above 
for "suggested" and controlled vocabularies.
[MA] We have removed the "suggested terms".

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).

ed.: For FrameSize, it says that the default unit is pixels, yet in the 
example float values are returned for unitless objects. Is that intentional?
[MA] The points were used as thousands separator. We have removed the 
points from the example.

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.

ed.: Why is it Samplingrate instead of SamplingRate?
[MA] We changed this to SamplingRate.

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.

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.

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

[0]http://www.w3.org/2008/WebVideo/Annotations/drafts/API10/LC/Overview.html

Received on Wednesday, 29 September 2010 07:12:30 UTC