- From: Daniel Park <soohongp@gmail.com>
- Date: Tue, 6 Apr 2010 11:07:59 +0900
- To: Silvia Pfeiffer <silviapfeiffer1@gmail.com>
- Cc: Soohong Daniel Park <soohong.park@samsung.com>, public-media-annotation@w3.org, Joakim Söderberg <joakim.soderberg@ericsson.com>, tmichel@w3.org
- Message-ID: <w2wf7c7d76e1004051907r9e70b188s476dcd139d2199d5@mail.gmail.com>
Thanks Silvia for your very valuable feedbacks on both documents and quick
review.
Again, thanks,
Daniel (on behalf of MAWG)
On Mon, Apr 5, 2010 at 9:14 PM, Silvia Pfeiffer
<silviapfeiffer1@gmail.com>wrote:
> 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.
>
>
> 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.
>
>
> 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").
>
>
> 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.
>
> Also, I believe that the API should be independent of a format and
> thus the sourceFormat and the subtype parameters are not useful.
>
> 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.
>
> 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.
>
> 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.
>
> 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).
>
>
> 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.
>
> Example:
> Identifier.value =
> "
> http://www.w3c.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.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-20090626.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-20090626.JPG
> "
> and id.type = "URI"
> and the other values as above in JSON
>
>
> 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"
>
> * 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.
>
> * 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"
> }]
> }
> }
>
>
> 7. Section 2.3.2.2 Creator
>
> * replace "StringObject" with "Creator"
>
> * 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/Author2"]
> }
> }
>
>
> 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".
>
> *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"
> }
> }
>
>
>
> 10. Section 2.3.3.1 Description
>
> * replace "StringObject" with "Description"
>
>
> 11. Section 2.3.3.2 Keyword
>
> * replace "StringObject with "Keyword"
>
> * there should be a list of values:
>
> interface Keyword: MAObject {
> attribute DOMString[] value;
> }
>
>
> 12. Section 2.3.3.3 Genre
>
> * replace "StringObject" with "Genre"
>
>
> 13. Section 2.3.4.2 Collection
>
> * replace "StringObject" with "Collection"
>
>
> 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)
> * replace "policy" attribute with "value"
> * 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;
> }
>
> * example needs to map the fields
>
>
> 15. Section 2.3.6.1 Publisher
>
> * replace "StringObject" with "Publisher"
> * publisher does not have a need for a language attribute
>
>
> 16. Section 2.3.8.1 FrameSize
>
> * Request should use the correct property name: replace
> "technical-properties" with "frameSize"
>
>
> 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;
> }
>
>
> 18. Section 2.3.8.5 Samplingrate
>
> * replace "UnsignedLongObject" with "Samplingrate"
>
> * example should have a common samplingrate for audio, e.g. 44100 Hz
>
>
> 19. Section 2.3.8.6 Framerate
>
> * replace "FloatObject" with "Framerate"
>
>
> 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
>
>
> 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
>
>
> 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
>
> * in the examples, the quotes (") inside the string need to be escaped
>
>
> 23. Section 3
>
> * if you introduce all the examples above for web service and for user
> agent scenarios, you might not need this section
>
>
> 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
>
>
> 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.
>
>
> Best Regards,
> Silvia.
>
>
--
Soohong Daniel Park
Samsung Electronics, DMC R&D
http://sites.google.com/site/natpt00
Email:soohongp@gmail.com <Email%3Asoohongp@gmail.com>, Twitter:@natpt
Received on Tuesday, 6 April 2010 02:08:32 UTC