Serving in-file covers to MPD

It’s been quite a while that I’m using a MPD server on my raspberry + hifiberry [1] to play my digital music on my amps. It works very well, the sound is very good and I can control it with my phone, laptop, tablet etc…  That is great.

What is less great is that MPD does not transmit covers to its clients (there is already an issue on MPD’s github [2] to let MPD natively find them).

What most clients do is asking you to setup a HTTP server above your music folder so that they can request the cover file with a query like:

GET /music/path/The%20Black%20Keys/Turn%20Blue/cover.jpg HTTP/1.1

This has 2 drawbacks:

1. You need to leave an access to your music folder to the HTTP server. I’m not found of this. Some people worked around this [3] but meh…
2. I don’t use cover files next to the songs. Whenever I rip a CD, I like to add the cover within the song files, so that it is nicely shown on my smartphone.

So I made a very simple python app to deal with this : mpdcoverserver. It has two options: a port and a music folder.

When the HTTP server receives :

GET /The%20Black%20Keys/Turn%20Blue/cover.jpg HTTP/1.1

it goes to <music folder>/The Black Keys/Turn Blue/, takes the first song, extracts the cover from it and serves it.

…Very simple…

You an find it there 🙂 : https://github.com/ochurlaud/mpdcoverserver

References

[1] https://www.hifiberry.com/
[2] https://github.com/MusicPlayerDaemon/MPD/issues/42
[3] https://github.com/uriel1998/yolo-mpd/blob/master/webserver_covers.sh

KDE Wikis: where should I write?

Hi there,

TL;DR

If you don’t know, go there first: https://community.kde.org/Guidelines_and_HOWTOs/Documentation_in_wikis

Some documentation issues

I’ve been asked a lot lately about some directions to document new projects in KDE.
I’ve seen as well an awesome tutorial being published on Planet KDE, with a very wrong address.

To counter that I wrote a page [1] that explains everything in details. If it’s not enough, just ping me and let me know.

A recap of previous episodes

During the sprint at CERN, we worked at a logical organization of our wikis [2].

On the Community wiki (https://community.kde.org), you’ll find a Guides and HOWTOs page, in which we try to centralize all the generic tutorials for KDE newcomers (and old ones as well :D). Go there whenever you have questions, take the time to read the pages, correct them if needed, add new ones if you think something is missing.

Even Specially if you’re new to KDE, write tutorial about what you find unclear, and ask us for review. You are the ones who know what information is missing!!

Cheers and have fun !
Olivier

Links

[1] https://community.kde.org/Guidelines_and_HOWTOs/Documentation_in_wikis
[2] https://blogs.churlaud.com/somefoobar/2016/03/17/we-reorganized-most-of-the-wikis-we-need-you/

I’ve been trying KMail and…

During Akademy, I saw that a lot of people had a very modern looking Mail program, which I didn’t know, and I was surprise to hear it was KMail.

I used KMail at work (during the whole year, yes this year), on a KDE4 station, and honestly, I didn’t like the experience. At all. So I kept using Thunderbird, which I’m used to etc. However, I grew bored of the interface, there is not much innovation, and most modules are just not maintained any more.

So seeing this nice UI I told my self “eh, let’s give a try again”. So I pacman-S-ed kmail2, which was overall 3 Mo only (I use Plasma and Korganizer, so I guess I already had all the dependencies people are complaining about).

Configuration

Setting up KMail’s account (I have 4) was quite obvious, like Thunderbird and most other Mail managers.

I had a lot of issues finding out how to define my Sent and Draft folders. The Trash was where I expected (in the account management) but the 3 others in the Identity management. Why? What is different between theses 3 folders?

This leads me to another question… Why identities and accounts are separated? Are there use-cases where you have one identity for 2 accounts? I have 4 identities, and 4 corresponding email accounts. So to me it’s just more thinking to have when I want to change configuration. Is my answer model based on my identity or my account? And the SMTP parameters?

If it were me, I would put the identity section as the first tab of the Accounts settings. But that’s only me.

Else, by going through the menus, everything gets done quite fast.

Overall user experience

Out of this, I really like the fact that it’s starts very fast and that it’s very responsive. Also since I use my Nextcloud instance for all my PIM-related stuff (contacts, calendars, …), everything is integrated thanks to Akonadi. Really, don’t kill it, it’s so great to set things up once for all programs.

I also followed the advice I was given (by Cola I think) to use the 3-columns disposition. The experience is just amazingly better (you can do that with Thunderbird as well, but it looks too clustered on my tiny screen).

My only problems so far are

• Bug 362575, which prevent unsubscribing IMAP folders, so I get several useless folders like “Contacts”, “Notes”, “Journal,” etc. (it’s a Microsoft Exchange account).
• Crashes when I try to affect a new tag to an email (I get a segfault).
• And finally I expected that selecting 3 emails and click “Reply” would create an email to all recipients. I would really like to have such a feature, but hey, after 2 days, I think it’s working quite good.

I’m also quite confused about “Local subscription”, “Server-side subscription”. What is a model (reply model from the config menu, model you save, or reply with personalized model)? Still don’t know :S.
Maybe you should ping the VDG/Usability guys and see what to change in the organization and names?

TL;DR

Finally my experience with KMail is a good experience, and I think I won’t need to go back to Thunderbird. Guys, you did great job since KDE4 on this project. There is still some bugs and UX issues, but IMHO you are on the right tracks. Keep up the good work!

QtCon: Plasma 5 running smooth on ARMv7!

Disclaimer: This is no official announcement, I report something I observed and that I found amazing.

Today at QtCon, I was introduced to a Plasma 5 session running on a Odroid-C1+ (using ARMv7, running Debian).

I was very amazed to see that it runs very smooth, and is very responsive. Moving windows, placing plasmoids on the desktop works with almost no glitch. As email management and file indexing is not really needed in this context, Akonadi and Baloo were disabled. Of course, it’s not very usable for intensive graphic use (watching videos, image editing, etc), but it’s alright for other use-cases.

And hey, the overall RAM use was less than 300 MB! (All together!!)

The take away here is:

If you hear someone saying that Plasma 5 and KDE software are bloated, they don’t know what they are talking about. They are just wrong.

Akademy: Let’s talk about music player and documentation

Hey,

I’ll be at QtCon and Akademy in Berlin, mostly as observer, I guess 🙂

I’ll have also two workshops/discussions on Tuesday 6th (see [1]).

Music player

For some time now, there were threads [2] about designing a new music player. The VDG people came up with a vision and some first design ideas [3] and I built a first specification page on the community wiki [4].

I’ll do a workshop which will deal about:

• what will make this player not just another player
• feature discussion
• architecture design
• use of the public libraries of plasma-mediacenter
• …what you want to add…

The first 3 points will be mostly a presentation of what I want to do, with discussions about how it can be done better.

I already wrote some code, but it was mostly to make some experimentation, the project was put on hold until this Akademy session, in order to start on the right basis.

Documentation and KApiDox

I also reserved a slot for KApiDox, the program that generates the api.kde.org website. The codebase changed a lot lately, and more and more projects are being generated. However, it’s still not very robust to errors (the whole process would break instead of just ditching the error source) and it appeared not to respond to every usercases.

If you think our API documentation is important and can/should be enhanced, please join the discussion so that I can know your needs (as API user or API writer) and enhance the whole thing in the future.

Links

[1] https://community.kde.org/Akademy/2016/Tuesday
[2] https://forum.kde.org/viewtopic.php?f=285&t=122273
[3] https://community.kde.org/KDE_Visual_Design_Group/Music_Player
[4] https://community.kde.org/Playground/MediaPlayer

The KApiDox poll results (at last!)

Hey!

I add to put on the side most of my contributions for some times, as I’m finishing my master thesis in end August, and that I still have some exams in parallel. However it’s important that I give you a feedback about what you expect KApiDox to be. I already apologies, this post is long, but hopefully worth it.

As some of you might remember, there was a survey about the future of KApiDox and more generally of api.kde.org. First: thank you for answering, it was very helpful. In this post I’ll review your answers and discuss some of them. Feel free to comment if you do not agree with my understanding or to share your point of view. This is important for the promotion of KDE products.

Who are you

I’m quite happy because I got quite a lot of answers, mostly by KDE developers. Most people seem to be using api.kde.org for the KDE Frameworks documentation. An interesting contribution was from a developer that uses only the Qt Frameworks because he founds the KF5 online documentation difficult to use. Well, let’s try to change that!

Current status

I worked at modernizing the old api.kde.org website. It’s unfortunately not finished. Most of you find the new design nicer, which really pleases me, but still a lot of you think it’s not good enough to attract new people. As next questions show, there is a usability problem to solve: too many clicks to access to one info, more crosslinks are needed… (@VDG: Help!)

People expect the design to be more responsible for mobile browsing. I must say that I have no knowledge about this. As usual, contribution welcomed: just contact me!

Some people refered as well to the search box which

1. Redirect to a page with the old design
2. Shows results for all libraries, with not very transparent names (Frameworks in module Frameworks5)

This will change. See next section.

The future

Searching

I’d like to let KApiDox generating the search box. This would have the benefit to isolate the results. If you search within the KF5 module, you don’t want to get all the KDELibs, Krita, KDevelop results. Only KF5. And that makes sense.

Versioning

About the API versions to show, most of you proposed generating only the major versions plus master (For example when Okular 5 will be released: okular4, okular5, master). This makes sense to me and so I’ll see how to do this.

Man/Qch files

Some people asked me about this. It still exists but hidden: https://api.kde.org/qch. Currently one script generates them and put them where to be found by links statically written on a hand-written page. I want KApiDox to handle this. It will first generate the full qch/man file by product (one for all KF5). I’ll think later how to make it smooth library by library if really needed.

Products organization

Some of you think only the Frameworks should appear here. Here is why I disagree: we don’t have the man power to maintain scripts generating the [Plasma applets, Okular, Marble, Amarok, KIPI, Krita,…] API documentation. Having a centralized place allow people using more easily what we propose. It only needs to be correctly done (and I hope it will).

Now come the question about how to organize things. There is no clear cut whether Plasma and Frameworks API must be on top, or considered only as one other KDE products. It is not my choice to promote one or another library: for now it will stay alphabetical. A problem with the idea of organizing in categories, is that it is difficult to understand this organization. Is Okular in Office or Graphic? I use it only to read PDF and epub, but you can also read pictures… Hum…

The inside

It might be less important for you, but I redesigned most of the code (written in Python). Currently everything is done through dictionaries, without too much exception handling. This makes KApiDox not robust at all. I really want to change that, and to ease in the same time the feature extension. Moreover it is part of the Frameworks, but cannot be used in the current state by people out of KDE. I really want to make that nicer, more robust, and more Pythonic. We’ll see 😛

About the expected documentation

This poll raised some comments about the documentation in itself (content) and what could be improved. It doesn’t concern KApiDox but all of us, to provide more useful documentation.

• The class-by-class documentation is mostly fine (Hurray!)
• Information about how classes and libraries fit and work together is missing. A more high-level documentation (less technical but more about the concepts) would be really appreciated.
• The introduction pages should link and name the main classes so that one doesn’t have to browse through all of them (through the awful class picker).
• More tutorial and examples would be really appreciated, directly in the class documentation or in the introduction pages. Remember my last post about this.
• Some API need reviews from people who are new to KDE: too much assumptions are made on the reader knowledge. This example was given:

  NormalizedRect TextEntity::transformedArea ( const QTransform &  matrix) const
  Returns the transformed area of the text entity. 

  Question: Why should one ever use such a method?

SOooooo

As you can see there is a lot to do. If you are interested in Python, Javascript, HTML, CSS or even Doxygen, please contact me. I’m sure there is work for more than me and it will allow the features to appear faster, and by that help the whole community!

I guess that’s all…. Oh and by the way: KDevelop, Krita and libgames, it would be great if you would join our front page…..

Writing up-to-date tutorials with Doxygen

The other day we were discussing on #plasma about KApiDox and what the Plasma team needed to write awesome documentation. Sebas and Martin were specially complaining about the fact that keeping a tutorial up-to-date was difficult because it is only text which will never be compiled for real by the writer, or not as presented.

The solution

I’d like to share the solution that Doxygen propose (adapted from the Doxygen documentation [1]):

The command is

\snippet <file-name> ( block_id )

Contrary to \include that includes a complete file as source code, this only quotes a fragment of a file. To refer to the same file you are documenting, use this as the <file-name>

For example, the putting the following command in the documentation, references a snippet in file example.cpp residing in a subdirectory which should be pointed to by EXAMPLE_PATH.

 /**
  * ....
  * A resource can easily be added with:
  * \snippet snippets/example.cpp Adding a resource
  * ...

A unique identifier refers to the snippet defined as followed

    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));
//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

The output of the snippet command is:

document->addResource(QTextDocument::ImageResource,
    QUrl("mydata://image.png"), QVariant(image));

What follows

I updated the wiki [2], and now you can continue writing awesome documentation about how to use your libraries.

You know what? The more it goes, the more I think that Techbase is slowly becoming useless… But Schhhhtttttt… this is a secret. 😀

Cheers and have fun !

Sources

[1] http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdsnippet
[2] https://community.kde.org/Guidelines_and_HOWTOs/API_Documentation#Code_Examples_in_APIDOX

KApiDox (or api.kde.org): I need your input !

Hi there!

As you might know, I’m the new maintainer of KApiDox, and by that I’m more or less responisble of the api.kde.org website.

KApiDox used to be a script for generating the KDE Frameworks (KF5) API. This is however changing: I would like to generate all KDE APIs with this tool.

It is on its way, but before going further I need your input.

We worked with Thomas (@Colomar) on a little survey about the api. This will take less than 5 minutes of your time but help a lot. To be helpful, you don’t need to actually use the KApiDox scripts, but only the api.kde.org website.

Please answer the questions here: http://survey.kde.org/index.php/612593/lang-en

It will help me a lot to make things better!

Cheers and have fun!

The future of KApiDox

Hello there,

I’ve been working hard to enhance KApiDox. I’d like to come back on what it is for, what I did and what I see for its future.

Tl;dr

I created a new branch in the KApiDox repository [1] and it’s currently in review on ReviewBoard [2].

Please review it, and if you have the corresponding rights, give me the green lights do put what I did in production. I think it will help KDE products to be more visible on the web. To know more, do read what follows. 🙂

What is KApiDox

KApiDox is part of the KDE Frameworks. As Aurélien Gateau wrote [3]:

KApiDox is a set of tools used to generate KDE Frameworks documentation. These command-line tools use Doxygen to do most of the work.

Currently you can use two tools: kgenapidox, to generate the documentation of a single framework and kgenframeworksapidox, to generate the documentations of all frameworks as well as the landing page which lets you list and filter frameworks by supported platforms.

You can see it working on [4].

Oh, and by the way, it’s written in Python.

What do I propose instead

The Frameworks are the only set of libraries that have a sort of visibility on the web. If other products, like say KDevelop or libkdegames, have public libraries, there is no easy way to generate the documentation and put it on the website.

Global idea

You already got it: the idea is to improve and correct what I pointed above. The new KApiDox would be one tool, that would be run over a set of repositories. It would read recursively all folders and look for CMakeLists.txt and metainfo.yml files. I’ll speak about the latter below.

The libraries are then organized in:

• products: it can be a group like KDE Frameworks, Calligra, KDevelop… or a single library like KIPI,…
• subgroups: Tier 1, Tier 2, …, Krita, …
• libraries: KApiDox, KArchive, ….

A nice landing page is automatically created, then subpages and the documentation. You can see an example in the tar.gz file attached to my review [2].

How can it be used by your projects?

The documentation of your projects can be generated if they provide a metainfo.yml file.

The minimal syntax, for an independent library is:

# metainfo.yml

description: Library doing X
maintainer: ochurlaud
public_lib: true  # This is the only mandatory key, don't forget it!
logo: path/to/logo.png

This would be understood as a product consisting in one library, which name is read from the CMakeLists.txt.

It’s a little more complex if you want to have groups and subgroups, you can add a lot of other keys (to define the group description, where the sources are, where is the internal documentation…) that are presented in the metainfo_syntax.md file [5] at the root of the repository (in the branch olivier/generate_all_repos).

The future

Since I don’t have the green light to actually use the KApiDox scripts, I don’t want to spend too much time on it, in case my proposition is refused. But I have ideas to go further.

• The tool can easily figure out if it is run over only one product or several or one library.. So the landing page could be different for each scenario.
• People told me that having different version available (like Qt does for the versions 4.8 and 5.x) would be a great plus. It’s quite easy if I teach KApiDox some git commands….
• KApiDox is designed to run only over public libraries (if the key public_lib is not true or not set the library is ignored). An argument could be used to generate as well the private libraries so that developers can use it for themselves.
• KApiDox can currently only work in our infrastructure. If it is supposed to be part of the KDE Framework, it should be usable by other people, out of the community. This means refactoring the code a little and putting what is only part of KDE in another place.
• …

Please review!

Now that you have a rough idea of what I propose, if you find it useful, please tell it, and review my works so that it can be used as soon as possible! The link is there: [2].

Links

[1] KApiDox on Quickgit (think to select the correct branch: olivier/generate_all_repos)
[2] Review on ReviewBoard
[3] Aurélien’s post
[4] API documentation generated by KApiDox
[5] metainfo_syntax.md

We reorganized (most) of the wikis, we need you!

…This post explains in more details what have done on the Community and Techbase, and what belongs where…

So we worked a lot on Community and the structure changed. It’s what I want to write about here.

More details can be found here:

• https://community.kde.org/Help:Contribute
• https://techbase.kde.org/Help:Contribute

What goes where?

What goes in Community?

You have a KDE project and need a place to coordinate, explain how to build from source or give some code guidelines, please write it under https://community.kde.org/Your_Project and add it (if it’s not already the case) on the front page, where it belongs. This is where the contributors of this project should go to find information about it.

So what goes in Techbase?

In Techbase we thing in term of products. If you have a product that can be build on or extended by third parties (plugins, API, scripting,..) then you should document how to extend it or build on top of it. We are working on a tutorial about this to help you to write this type of documentation. Basically an external developer needs to know how the library work (API), have a high level overview of what can be done (and why), how to troubleshoot or debug when it doesn’t work, how to get help. Of course you can (should?) add a link to you community space to push them to contribute to your project…

You should keep in mind, that this is a reference for people who are not in the KDE community: they are users of your technology. It’s more than possible that your Community space will link to the documentation in Techbase because contributors need this information as well.

What is still to be done?

On our side

Some projects are still hidden in Techbase, and need to be moved to Community. When it’s done we contact you to sort and merge them with your current documentation.

The tutorial section on Techbase is still messy, and we are slowly reorganizing them (see the Guidelines and HOWTOs page). It won’t be all on community! The documentation on, say, how to localize a program with Ki18n definitely belongs to Techbase, whereas how to use git on our infrastructure doesn’t.

We are working with the VDG team to organize cleverly Techbase frontpage

Still some links are red, we are trying to correct that as fast as we can.

On your side:

It really depends on your project and products but overall:

• Check that your links to the wikis are still up to date in your websites.
• Maybe take this opportunity to be sure all your documentation is up-to-date? Delete old or irrelevant pages?
• If you are concerned, add your product to the Techbase front page and begin documenting
• Tell us if something is missing, should be enhanced or anything else (but with argumentation please… no “Better before, it was” will be accepted 🙂

We really need you for this!

This said, as usual:

Cheers and have fun!

PS: Consider supporting KDE e.V.! It might be small for you but it’s great for the community.
Via Paypal for one-time donations
Become an ongoing supporter and official supporting member