RE: [W3C Media Annotation WG] Request for Expert Review (API)

Dear Sylvia, all,

I have gone through your review of the API document and have provided my
comments below ([CP]). In most cases I agree, in some cases I would like to
see/hear the opinion of the group.

In any case, thanks a lot for the valuable (and in-depth) feedback!

@ Media-annotation group, this is related to my action item 231: look at
Silvia's comment (I have done more than looking).


Kind regards,

Chris 

Ghent University - IBBT
Faculty of Engineering
Department of Electronics and Information Systems (ELIS)
Multimedia Lab Gaston Crommenlaan 8 bus 201
B-9050 Ledeberg-Ghent
Belgium
 
t: +32 9 33 14959
f: +32 9 33 14896
t secr: +32 9 33 14911
e: chris.poppe@ugent.be
 
URL: http://multimedialab.elis.ugent.be






-----Original Message-----
From: public-media-annotation-request@w3.org
[mailto:public-media-annotation-request@w3.org] On Behalf Of Silvia Pfeiffer
Sent: maandag 5 april 2010 14:14
To: Soohong Daniel Park; public-media-annotation@w3.org
Cc: Joakim Söderberg; tmichel@w3.org
Subject: Re: [W3C Media Annotation WG] Request for Expert Review

Dear Soohong, all,

Here is now my feedback on the API document.

On Tue, Mar 16, 2010 at 3:17 PM, Soohong Daniel Park
<soohong.park@samsung.com> wrote:
>
> [2]
>
> API for Media Resource 1.0 [Version 09 March 2010]
>
> http://www.w3.org/TR/2010/WD-mediaont-api-1.0-20100309/
>
> Abstract: This specification defines a client-side API to access metadata
> information related to media resources on the Web. The overall purpose of
> the API is to provide developers with a convenient access to metadata
> information stored in different metadata formats. The API will be
introduced
> in an abstract manner using the interface definition language Web IDL.
> Thereby, the Media Ontology Core Properties will be used as a pivot
> vocabulary in the API.


FEEDBACK ON API:

1. Section 2.1: MAObject

You need to introduce MAObject better. What is it for? IIUC it is the
parent class to all return types - i.e. it is a generic list of
attributes for any property. I am not actually sure it is that useful
- in an application, that is information about the transcoding. I
would probably prefer if the properties were subclassed from a
MetadataSource object. But I am not sure you need that, either.

[CP] I agree, in the new version this is better explained.

2. Section 2.1: Language

I would not define Language as a part of the return value of some of
the properties - it is very unlikely that a annotation uses different
languages for different properties. I would only manage the language
on the level of the metadata source level.

[CP] It could be the case that different annotations are available for one
media resource (e.g. 3 MPEG-7 files). I agree that within one annotation
typically the language remains the same, but I would not be surprised to see
multi-lingual annotations appear in the future (e.g., a review by a French
man on a Hungarian movie).

3. Section 2.2: setContext

I would suggest renaming that function. Also, your parameters are not
quite right:

boolean setMAResource ( in DOMString mediaResource, in optional
MetadataSource[] metadataSources);

(note the replacement of "Object" with "MetadataSource").

[CP] Any suggestions on the new name? (setSources, setMediaResource +
setMetadataSources, ...)?

3. Section 2.3

You need to make sure that the full definition of "getProperty" is
printable (for me, it went off the right edge of my page).

Also, you only return one MAObject IIUC, so don't make the return value a
list.
[CP] Well we want to include the possibility that you can get back
information from different annotations (EXIF, DC, MPEG-7) even of the same
standard (2 independently created DC annotations). Furthermore, for some
properties you could get back different values (e.g., if a movie has two
titles), different languages (French and English title) and so on. 


Also, I believe that the API should be independent of a format and
thus the sourceFormat and the subtype parameters are not useful.


[CP]The idea was that in some cases an application might want to get back
metadata of a specific format only. In any case, when not including a
sourceformat you get back the metadata regardless the underlying format. The
subtype allows to refine a search for metadata (e.g., requesting for the
contributors gives both producers and actors. Using the subtype you could
ask for only those contributors that are actors).

Also, I believe the API should be independent of the language in use -
if you really wanted language selection to be made on the metadata
files, then this should be handled at a different level.
[CP] If nothing is filled in for the language argument it is in fact
language independent. Do you think that the optional language argument is
really an issue?


Further, I believe your "fragment" parameter may also refer to data
tracks in media resources, which I find a more important parameter
than all the other optional one, so would prefer to have that as the
second parameter.
[CP] I tend to agree that this parameter could be used the most so I can
update the order.


Thus, it should probably look like:

MAObject getProperty(in DOMString propertyName, in optional DOMString
fragment);

Note that I am not quite sure how to represent in Web IDL that the
MAObject is the union of all the possible return values for all
getProperty requests. I don't think how it is currently done is quite
correct, since it only returns the parent class, not the child
classes.

[CP] Well, all possible return values (depending on the requested
propertyName) are objects that implement specific interfaces (which inherit
from the MAObject interface). I assume(d) that this can be represented in
WebIDL as such.


Further, I would suggest as an example for how to introduce this into
a UA: the  following example for how to introduce it into HTML5:

interface HTMLMediaElement : HTMLElement {
  ...
  getter MAObject getProperty(in             DOMString propertyName,
                                            in optional unsigned long
trackIndex);
  ...
}

(I don't think any other type of fragment than the track index makes
sense for HTML5).
[CP] Adding such an example seems like a good idea to me. However, I am not
sure about the trackIndex, or the absence of the other arguments (as
mentioned above).


4. Section 2.3.1.1 Identifier

Your examples are all a bit incomplete in their JSON representation. I
will write a full example for this section - the others need to be
changed logically to this, too, though I will only indicate this where
it may be confusing.

[CP]I agree, this is being worked on. I believe your example is an excellent
starting point!


Example:
Identifier.value =
"http://www.w3c.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-2009
0626.JPG"
Identifier.type = "URI"

Usage as a service:
* Request: http://example.com/my-media-resource?ma-query=identifier
* Response in JSON:
{    "Identifier": {
           // This first lot is inherited from MAObject, though I am
unclear what the values should be
            "unstructuredValue": ???,
            "uri" : ???,
            "sourceFormat": ???,
            "fragmentIdentifier": ???,
            "mappingType": ???,
        "value":
"http://www.w3c.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-2009
0626.JPG",
        "type": "URI"
     }
}



Usage as a UA call in JavaScript in a Web Browser:

video = document.getElementByTagName("video")[0];
id = video.getProperty("identifier");

Resulting in:
id.value =
"http://www.w3c.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-2009
0626.JPG"
and id.type = "URI"
and the other values as above in JSON

[CP] I am assuming that this example is in the case of the getProperty has
been added to HTML5?
However, in the current state it would rather be:
id[0].value =
"http://www.w3c.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-2009
0626.JPG"
id[0].type = "URI"  


5. Section 2.3.1.2 Title

* remove "Language" from the inheritance list - should not be per
property but per metadata resource

* Example should be:
title.value = "MAWG Stockholm 20090626"
title.type = "Video title"


[CP] I agree. However, for the type, the fact that it is a title of a video
is typically not always described in the metadata itself. Would you suggest
that the application needs to deduce this information somehow? (e.g., from
the fact that the mediaelement is a HTMLVideoElement like in HTML5?).


* JSON response should be as in the identifier example above

* add a UA JavaScript example as above

* similarly adapt 2.3.1.3 Language, 2.3.1.4 Locator


6. Section 2.3.2.1 Contributor

* why are we suddenly using "id" and "role" as attribute values? They
should continue to be "value" and "type" like in the previous
properties for consistency.

[CP] Interesting, it might indeed be a good way for consistency although the
use of "id" seemed more appropriate to me than "value" when talking about
contributors. I leave this open for the group.


* in this example, you have a set of return values, so the spec needs
to look different:

interface Contributors {
    attribute DOMString value;
    attribute DOMString type;
}

interface Contributor: MAObject {
    attribute Contributors[] contributor;
}

* JSON reply thus looks something like:

{    "Contributor": {
           // This first lot is inherited from MAObject, though I am
unclear what the values should be
            "unstructuredValue": ???,
            "uri" : ???,
            "sourceFormat": ???,
            "fragmentIdentifier": ???,
            "mappingType": ???,
            "contributor": [ {
                     "value": "http://individuals.example.com/Contributor1",
                     "type": "editor"
                     },
                     {
                     "value": "http://individuals.example.com/Contributor2",
                     "type": "producer"
                     }]
     }
}

[CP] As mentioned before we could always have a set of return values.


7. Section 2.3.2.2 Creator

* replace "StringObject" with "Creator"

[CP] StringObject was used for each property that just holds a string. It
might indeed be better to define appropriate interfaces.
Will change this if the group agrees.


* again, the value is a list, so it has to be something like:

interface Creator: MAObject {
  attribute DOMString[] values;
}

* the JSON looks something like:

{    "Creator": {
           // This first lot is inherited from MAObject, though I am
unclear what the values should be
            "unstructuredValue": ???,
            "uri" : ???,
            "sourceFormat": ???,
            "fragmentIdentifier": ???,
            "mappingType": ???,
            "values":
["http://individuals.example.com/Author1","http://individuals.example.com/Au
thor2"]
     }
}
[CP] Same remark as with contributor


8. Section 2.3.2.3 CreationDate

* you talk about both "CreationDate" and "Date" here. If you want this
value to have a type of e.g. "creation date" and "publish date", it
should not be called "CreationDate", but only "Date".
[CP] I agree that "createDate" as propertyname is not a good name to
represent both "Create Date" and "Publish Date" subtypes. I am not fond of
the use of "date" as propertyname either since it sounds a bit too generic. 


*also, this may possibly return a list of dates rather than just one value


9. Section 2.3.2.4 Location

* your response value should be a JSON list something like:

{    "Location": {
           // This first lot is inherited from MAObject, though I am
unclear what the values should be
            "unstructuredValue": ???,
            "uri" : ???,
            "sourceFormat": ???,
            "fragmentIdentifier": ???,
            "mappingType": ???,
          "name": "San Jose",
          "longitude": 37.3398...,
          "latitude": -121.88...,
          "altitude": 0,
          "system": "GPS"
     }
}
[CP] I agree


10. Section 2.3.3.1 Description

* replace "StringObject" with "Description"
[CP] Same remark as for creator

11. Section 2.3.3.2 Keyword

* replace "StringObject with "Keyword"
[CP] Same remark as for creator

* there should be a list of values:

interface Keyword: MAObject {
  attribute DOMString[] value;
}


12. Section 2.3.3.3 Genre

* replace "StringObject" with "Genre"
[CP] Same remark as for creator

13. Section 2.3.4.2 Collection

* replace "StringObject" with "Collection"
[CP] Same remark as for creator

14. Section 2.3.5.2 Policy

* replace "Policy" with "License" as it is called in the Ontology (or
do it the other way roung)
[CP] Done (the other way round)

* replace "policy" attribute with "value"
[CP] I agree


* add a "link" attribute (or something similar) with a link to the license
text

interface License: MAObject {
  attribute DOMString value;
  attribute DOMString link;
  attribute DOMString organization;
  attribute DOMString type;
}
[CP] No objections.

* example needs to map the fields
[CP] I agree

15. Section 2.3.6.1 Publisher

* replace "StringObject" with "Publisher"
* publisher does not have a need for a language attribute
[CP] I agree


16. Section 2.3.8.1 FrameSize

* Request should use the correct property name: replace
"technical-properties" with "frameSize"
[CP] I agree


17. Section 2.3.8.4 Format

* doesn't need a language attribute
* replace "StringObject" with "Format"
* interface should be:

interface Format: MAObject {
  attribute DOMString value;
}

[CP] I agree

18. Section 2.3.8.5 Samplingrate

* replace "UnsignedLongObject" with "Samplingrate"
[CP] Same remark as for creator

* example should have a common samplingrate for audio, e.g. 44100 Hz
[CP] I agree

19. Section 2.3.8.6 Framerate

* replace "FloatObject" with "Framerate"
[CP] Same remark as for creator

20. Section 2.3.8.7 Bitrate

* you should rename it to AverageBitrate - anything else doesn't
really make sense in the context of modern codecs
* should be provided in kbps (kilobit per second)
* replace "FloatObject" with "AverageBitrate"
* example value could be more useful, e.g. 45.06 kbps
[CP] I agree

21. Section 2.4 getDiagnosis

* the request should not have a "=" at the end of the URI
* same for 2.5.1 and 2.5.2 examples
[CP] I agree


22. Section 2.5.3 getOriginalData

* the return value should not be a DOMString list - it's simply a
single, very long string for the requested source format - not for all
possible formats
[CP] We assume that for one format multiple annotations can be available
(e.g., different MPEG-7 files). So this is the reason for the list of
DOMStrings


* in the examples, the quotes (") inside the string need to be escaped
[CP] I agree

23. Section 3

* if you introduce all the examples above for web service and for user
agent scenarios, you might not need this section
[CP] I agree

24. Section 4

* mentions "setting metadata" - I am not sure that can be done easily
across formats actually ... I'd be curious how you will realise that
[CP] Indeed, this is a left-over of previous versions, we do not consider
setting of metadata, I would be curious as well to see it realized :)


Uff, got through the sections! I am quite happy with the documents
overall, so please take my feedback as improvements on an already good
set of documents.
[CP]Thanks for your effort! It is good to have external people read the
document in-depth to get rid of some obvious (and less obvious) mistakes.

Best Regards,
Silvia.

Received on Wednesday, 14 April 2010 15:43:54 UTC