Missing docs in ubuntu website

[Alejandro J. Cura]

There are no docs for the thumbnailer's QML plugin in https://developer.ubuntu.com/api/qml/current/

[Michał Karnicki (karni)]

Not only for the QML plugin, but there's no docs for C++ API either.

[Michi Henning (michihenning)]

David Calle has kindly agree to take care of the publishing of the QML doc. (I didn't assign the bug to him because I can't find the launchpad ID.)

The Qt interface has complete doc that's provided in the doc package (as soon as we do the next landing).

[David Callé (davidc3)]

Added myself.

[Michi Henning (michihenning)]

Thanks David!

Set to triaged for thumbnailer so we can still track it.

[Michi Henning (michihenning)]

Doc for Qt interface has just passed silo approval. Should land within a few hours.

[David Callé (davidc3)]

It has been published in Apps > QML > Tutorials: https://developer.ubuntu.com/en/apps/qml/tutorials/use-ubuntu-thumbnailer/

[Michi Henning (michihenning)]

Thanks for that David! I spotted a few minor errors and omissions. Could you look at these please?

In "How to use it":

image://thumbnailer/<file path>"

should be

image://thumbnailer/<file URI>

Also, on the same line, the comment "local videos and pictures" really should be "local videos, audio files, or pictures"

image://albumart/album=Blur:+The+Best+Of&artist=Blur"

It looks like the "+" signs should be "%20"? (This also appears in the URI after this one.)

The "Cosmos Laundromat" and "Cry Me A River" URIs should have %20 instead of spaces.

It might be nice to add an example that same box that shows how to extract a thumbnail from an image file (just to make it clear that this can be done too).

It would be good to mention the media.getArtUri() method, which creates a thumbnailer URI. Otherwise, people are likely to cobble the URIs together by hand and get it wrong half the time...

I think the page needs some explanation of semantics. Specifically:

The thumbnailer always preserves aspect ratio.

Returned thumbnails may be smaller than what was asked for because the thumbnailer never up-scales. If the original artwork is smaller than what was asked for, the largest possible thumbnail will be returned. Thumbnails are never larger than 1920 pixels in the larger dimension (even if the original artwork is larger).

Requests with either dimension < 0 are invalid and return an error.

Requests for (0,0) mean "as large as possible" (subject to the 1920 pixel limit).

Requests for (x,0) or (0,y) mean the same as (x,x) and (y,y), respectively.

[Michi Henning (michihenning)]

Sorry, the media.getArtUri() method doesn't apply to QML. It is provided by the mediascanner API.

But that raises another question: we also have a Qt API. The doc for that is provided by the thumbnailer-qt-doc package. Would it be worth mentioning this somewhere?

[Michi Henning (michihenning)]

"Requests for (x,0) or (0,y) mean the same as (x,x) and (y,y), respectively."

Correction:

(x,0) means "I don't care how tall, but no wider than x". The height is determined by the aspect ratio.

Similar for (0,y), which leaves the width unconstrained.

[David Callé (davidc3)]

Thanks Michi, that's very useful. I've updated the page. The example will be updated as well.

[Michi Henning (michihenning)]

Great, thanks David! Can you please let me know when the example image is done, so I can close?

[Michi Henning (michihenning)]

Hi David, any movement on this? The image still shows the incorrect information. Also, a link to the qt doc package would probably be useful.

[Michi Henning (michihenning)]

This is still not fixed. Can we please update the incorrect information?

[David Callé (davidc3)]

Excuse me Michi, but I'm not sure which changes you want here. Is it just the formatting of URI (which are, in all displayed cases, correctly parsed by Qt/QML)?

[unity-api-1-bot (unity-api-1-bot)]

Sorry David, I was going by your comment #10 which mentioned that the example would be updated.

image://albumart/album=Blur:+The+Best+Of&artist=Blur

Does this really work? (I can't try it out right now.)

If all the examples in the image work, then we can close this. Can you confirm?

[David Callé (davidc3)]

Just tried and it works.

image://albumart/album=Blur:%20The%20Best%20Of&artist=Blur
image://albumart/album=Blur:+The+Best+Of&artist=Blur
image://albumart/album=Blur: The Best Of&artist=Blur

All return the same result.

[unity-api-1-bot (unity-api-1-bot)]

Very cool, thanks for checking! And my apologies for my mistaken reminder!

I'll mark as fix released.