RE: [todo] Response to your LC Comment -2419 on Media API spec

Dear all,

I started drafting some answers to Robin's comments on the API doc. It
includes a number of questions to the group. Please see my comments inline.

Kind regards,
Chris

-----Original Message-----
From: public-media-annotation-request@w3.org
[mailto:public-media-annotation-request@w3.org] On Behalf Of Thierry MICHEL
Sent: Wednesday, September 29, 2010 6:17 PM
To: public-media-annotation@w3.org
Subject: [todo] Response to your LC Comment -2419 on Media API spec

Robin is not fully satisfied with the following remaining issues.
We must respond to Robin on these issues.


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


Issue 2419-A:
-------------
>> 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;


[CP] I have added the proposed sentence to the API document: "User agents
that support [HTML5] MUST expose the MediaResource interface on objects that
implement HTMLMediaElement." (The most recent version of the API document
can be found on:
http://dev.w3.org/2008/video/mediaann/mediaont-api-1.0/mediaont-api-1.0.html
). And included the proposed Web IDL statement.



Issue 2419-B:
-------------
>> 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?

[CP] The most recent version of the API document can be found on:
http://dev.w3.org/2008/video/mediaann/mediaont-api-1.0/mediaont-api-1.0.html
 If needed I guess we can split the API in a synchronous and asynchronous
version. What is the opinion of the group on this?


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

[CP] The asynchronous version does not solve the idiomaticity, it still
includes the filtering in the getProperty parameters. I do not see the big
advantage of shifting the complexity to the code that is calling the API. In
this case the implementation of the API has to return all metadata
corresponding to a certain request every time. The filtering would allow to
avoid this. Do we need to optimize the ease of implementing the API or of
using the API?


Issue 2419-C:
-------------
>> 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?


[CP]It was our opinion that the name getPropertyNamesWithValues might be
misleading. This method only returns the names of the properties that would
return values if they were requested for using the getMediaProperty method.
Therefore the name was renamed. We assumed that your suggestion on exposing
the properties directly is related to your previous comment.


Issue 2419-D:
-------------
>> 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?
[CP]Yes, we have renamed the MAObject interface to MediaAnnotation
interface.


Issue 2419-E:
-------------
>> 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/Typed
Array-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.
[CP] I can change the  "attribute DOMString unstructuredValue;"  to
"attribute ArrayBuffer unstructeredValue;" and refer to the TypedArray spec
like is done in the File API. However, using the ArrayBuffer seems not very
adequate for representing strings. So maybe we should have an attribute
DOMString unstructeredTextValue; and attribute ArrayBuffer
unstructeredBinaryValue;?


Issue 2419-F:
-------------
>> 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.
[CP] So this issue is resolved?



Issue 2419-G:
-------------
>> 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?
[CP] This would be an ontology issue. I can change this to CreationDate if
wanted.


Issue 2419-H:
-------------
>> 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.
[CP] This is still not done

Issue 2419-I:
-------------
>> 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.
[CP] I have added the latter to the document.


Issue 2419-J:
-------------

>> 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.
[CP] The paragraph/sentence just holds what you proposed. It can be found in
http://dev.w3.org/2008/video/mediaann/mediaont-api-1.0/mediaont-api-1.0.html
#security-considerations 


Issue 2419-K:
-------------

>> 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!
>
[CP]Joakim, can you check this?

Received on Monday, 11 October 2010 11:36:05 UTC