Setup wizard for picard

Hi @outsidecontext , I am continuing our discussion here. For those who are unaware, this thread is a continuation of PICARD-292.

I’ve made some changes to the scenes and added more detail. These are just rough figures, without modern design, but they will suffice for now. Currently, I’m brainstorming additional main features to include in the wizard.

I am attaching the screenshots in the thread

1 Like


Just two typos in the title:

a) Plugin Management (40% screen)
b) AcoustID Fingerprinting (80% screen)

Or is this topic just about other ideas to show in this wizard?


Thanks for pointing it out :sweat_smile:, I will fix that.
Right now, these are just UI Mockups

General Comments:

  • My (limited) understanding of user interfaces is that the whole “Click here to…” stuff should be avoided if at all possible.
  • I suggest that you standardize on using the term “directory” rather than “folder” to be consistent with Picard. EDIT: Apparently Picard is not consistent in the terminology used.

In the “Music File Location” screen:

  • Is this intended to select a single root folder, or multiple directories? I believe that Picard currently only supports a single directory in the option settings.
  • EDIT: This is a bit confusing because the “Allow selection of multiple directories” option setting only applies when the “File → Add Folder” dialog is displayed. The way it is shown in this screen seems to suggest that you can select multiple folders as selected in the initial display of the dialog. This seems to be confused with the “Begin browsing in the following directory” option setting which only allows a single directory.
  • EDIT: This could also be confusing because it isn’t clear whether this is the starting directory specified in the “Begin browsing in the following directory:” setting, or the root destination directory when saving files specified in the “Destination directory:” option setting.

In the “File Naming and Organization” screen:

  • Am I correct in assuming that the radio button selections are the available presets?
  • How do you select the “Custom” option, since there is no associated radio button?
  • With “Custom” are you selecting a file naming script title, or is that intended to actually enter the script? For a new user, they may not even know that the file renaming is done via a script, let alone how to write one.
  • EDIT: You might consider adding a “Files will be named like this:” section to clarify the output for the selected file naming option, similar to what is displayed in the “File Naming” page in Picard’s option settings.
  • What does the “Enable folder organization” option mean? Is this intended to set the “Move files when saving” option? If so, there should probably be a corresponding “Rename files when saving” option as well.
  • I know that this is just a mockup, but the caption says “Progress: 20%” but the progress bar shows 30%.

In the “Handle Duplicates” screen:

  • Is this section something new, because I don’t believe that this functionality and option settings currently exist in Picard?
  • There is no “Progress: xx%” caption above the progress bar as there are on the other screens.

In the “Plugin Management” screen:

  • I understand that this is just a mockup, but it appears that the plugins you have listed are actually user scripts (which do not apply to Picard).
  • How are you determining which plugins to show for selection? Are they taken from the list downloaded by Picard during startup? If so, how are you selecting from the list? If not, and the list is hard coded, what happens if (when) a plugin has been removed and is no longer available?
  • What will be displayed when the link is clicked?
  • I know that this is just a mockup, but the caption says “Progress: 40%” but the progress bar shows 70%.

In the “Acoustic Fingerprinting” screen:

  • This seems to lead the user to believe that this is the best option for identifying the releases for their music files (using the “Scan” function) when, in fact, it is really a last resort. The preferred method is always using the “Cluster” and “Lookup” functions. This is doing the user a disservice by promoting the file matching workflow that yields the poorest match results.
  • I know that this is just a mockup, but the caption says “Progress: 50%” but the progress bar shows 80%.

On the “Thank you” screen, where is the “” link intended to go that allows the user to provide feedback?

EDIT: Is the intent that this wizard can be executed more than once? If so, on subsequent runs will the selections on the wizard screens show the user’s current option settings? This is an implementation detail, but if it shows the current option settings, will it take into account any active option profiles or will it show the user’s base settings?

EDIT: Perhaps the opening screen of the wizard should make it clear that it will help with the basic settings to get the user started and that they should review the full list of option settings to take advantage of Picard’s advanced functionality.


@nullhawk - Thank you for continuing to devote your time and energy into some thoughtful straw-men screenshots - these are IMO extremely valuable in helping us all think about what might be useful here.

Although my own thoughts about a wizard were more about taking a novice user through the actual tagging process, a setup wizard is at least as useful.

However a few thoughts about the screen shots above…

  1. You have clearly put a LOT of thought into these. Thank you again.

  2. I like the wizard progress bar, but it would also be nice to have a “Page 3 of 10” in the title bar.

  3. Introduction - I quite like the jaunty tone of the initial page - obviously there is quite a lot of scope for tweaking the text, but my only comment at this stage is the “Picard is a powerful tool” paragraph perhaps needs to be a bit clearer about what Picard can do and equally important what it cannot do or is not great at doing. This page also misses what I consider to be the entire point of Picard is that it is designed to automatically tag files with information from a massive crowd-sourced online database, which are largely organised around (single and album) "releases - and it is not (IMO anyway) really a tool for manual tagging or for tagging individual files. We might also want to say that the answers you give here are not set in stone and you can change them later if you need to. (Obviously through normal Options, but I think it might be nice to allow the user to rerun the wizard and it to show the user the existing settings for them to confirm or change.)

  4. Music File Location - this page needs more explanation because e.g. when you are setting out to tag your existing library, you may well want to set the root folder to a NEW location (to save to) rather than the existing location of your library.

  5. File Naming and Organisation - again this page needs some more introduction about how Picard structures releases into directories and renames the files to a standard format that the user can choose. I like the format you show here (which is simpler than the naming script format), but clearly there is going to have to be some translation back and forth from script language, and this also needs a comment (or we need to change the script language to use “” rather than “%”. IMO there also needs to be a warning that using track-only tags in the path can lead to files being scattered around - or even better we need to have Picard give a heavy handed warning about this.

  6. Handle duplicates - an option to delete one or other of the duplicate files is not shown here. Obviously it is a big step to delete files (or even move them to the recycle bin), but if a user has duplicate files and needs to dedup. them, then perhaps Picard should try to help. We also need to be clear whether xxx.mp3 and xxx.ogg are considered duplicates, and how Picard might choose which to keep and which to delete.

  7. Plugins - this is a whole pandora’s box here. My personal view is that we need to be VERY careful indeed which tiny subset of plugins we show here (if indeed we show any) and I personally believe that all but possibly one or two plugins are advanced functionality and should wait until the user has more experience, and a mention (on the last or penultimate wizard page) that plugins are available when they are comfortable and knowledgeable enough about Picard to want to tweak things is all that is needed.

  8. Acoustic fingerprints - is this genuinely core functionality that novices should be using (and I genuinely don’t know the answer)? My own view of Scan vs, Cluster is that Scanning is good for single files and for when Clustering doesn’t work, and it is NOT so mainstream as to have a wizard page for completely new users (because it potentially gives them a sub-optimal steer. To put this page into context, perhaps the wizard needs an intro page on workflows before you offer them this? (Also a separate workflow wizard might also help here.)

  9. Summary - can we have some text saying that they can go back and change any answers they are having second thoughts about (and can rerun the wizard and change answers or use the standard options pages to change them too).

  10. Final page - This is far too confident IMO - we cannot guarantee that the settings will “handle your music files correctly”. The link should perhaps be to the community pages.

Thanks again for your efforts. My comments are (obviously) only the thoughts of one person, and I very much hope that many others will chime in with their own ideas.

1 Like

In addition to the comments (and additional edits) in my earlier post, I just had another more general thought about this project. If the intent of this wizard system is to provide some basic education to a new user and to get input for the basic settings, perhaps there should be more screens with a more expanded explanation of the settings on that screen?

An example of this might be the screen that gets the setting for the root directory to use when saving files, where the descriptive text might be something like:

When Picard saves the updated audio files, it can also optionally move the files to a new directory structure that can be generated automatically as part of the file naming script. You can also specify the starting (root or top level) directory under which the generated file directory structure is created.

Do you want Picard to move the files when saving? [selection options for “Yes” and “No” (checkbox or radio buttons)]

What directory would you like to use as the starting top level directory for the generated file directory structure when Picard is set to move the files? [text line input with option button to use the system file browser to select the directory]

I realize that having one screen for each set of related options might end up being a few more screens in the wizard, but I think having the expanded description / explanation of the options will ultimately help the new user understand how Picard operates, and allow them to make more informed decisions regarding the option settings they are selecting. If the number of screens becomes excessive, perhaps there could be a pull down list in the footer of each screen (in addition to the “Previous” and “Next” buttons) to select a specific screen to display. This would be especially useful if the user were to re-run the wizard, but was only interested in reviewing some specific sections (without having to step through every screen to get to the “Finish” button).


Absolutely agree with Bob @rdswift 's comments.

Thanks for tackling this nullhawk! Great to see some concrete progress on this. Apologies again to you and @outsidecontext for coming in sideways when you were discussing this in IRC - I hadn’t realised that this was a GSoC project!

I would probably still like to see a new user walkthrough wizard - how to use the basic interface - but that is out of scope for the GSoC project. I’ll post my quick brainstorm here, for future reference:

re. the design of the Wizard you are working on here, I imagine there’s not much to be modified - that it will reflect the styling of the users operating system? (but I can still help make it look flash, see notes re. images below)

My feedback:

  • I would keep the text very minimal, but include a (possibly at the bottom of every panel, in the same place) note that things can be changed and further customised in Settings.
  • I would remove some of the ‘fluffy’ text. The welcome panel can be cut way down. I am happy to help make it friendly and welcoming with images instead! I just trialed some nice Picard images in PICARD-2845.
  • If it’s not a very long wizard, numbers might be better than the % bar, which tends to indicate longer processes. If it’s something like ‘1/8’ most users should feel like the end is within reach.
  • It might be a more efficient use of your time to develop this with text/a wiki/a doc of some sort, rather than Qt screenshots, until later - but up to you!

Specific pages (I’m not going into detailed feedback yet, but this is what stood out):

  • Music File Location: I don’t ever use the ‘select folder’ option. I drag and drop the folders I want to work with into Picard. This should probably be explained, or the panel reconsidered, especially considering we don’t recommend people load their entire music collections into Picard anyway.
  • They are the most obvious settings in Options, but a panel with these three checkboxes might still be useful: rename files move files rename files.
  • Other much-used settings are how users want to handle artwork.
  • As @sophist has said, a number of these should probably be reconsidered. You may even end up with a very sparse Wizard, but that is not a bad thing imo! We can always expand. It might also be fine to have some panels just say “this is the default folder naming script: [ABCD]. You can change it any time in settings”.

Whether or not I agree with @rdswift’s comments re. having more descriptive text depends on what the goal is - is this a setup Wizard, which helps users get started with Picard as quickly as possible? Or is it user onboarding, where we try give users a tutorial?

A big question I have:
Where are people clicking into this Wizard from? Do we want to give them a path back into the Wizard in future, and if so, where is that link/button?

Sorry for the delay in feedback on the ticket, by the way - I didn’t forget, but this is a big undertaking, with a lot to think about. Thank you for taking it on!


I share @aerozol 's concerns about “fluffy” text - for every user who has a warm emotional response to fluffiness, there will be another who hates it. I think it needs to be simple and direct but still friendly without being “fluffy” (if anyone can work out what that means in practice).

I disagree here - this is IMO NOT the place for minimalism. We definitely need to keep the text short and basic (and provide a URL link to the relevant documentation page if the user needs more detail), but there has to be a basic explanation in a wizard for new users who literally know nothing about Picard at this point.




Thanks @rdswift for your views

  • That was my mistake, The music file location will be selecting single folder at a time, I had used “(s)” by mistake their
  • Yes, these options were shown in the picard itself

    Screenshot 2024-03-26 173107

  • Thanks for pointing it out, Custom button also needs radio button and I surely missed it

  • For that I have added “?” button for new users to know about the naming script,
    this button will open a dialogue box explaining about that

  • Considering this, I think it would be better to create a new popup button for entering custom naming convention just like you mentioned in that “File naming” page has.

  • Yes, you are correct, but I thought “folder organisation” would refer to both, but as you suggested showing them separately will be more understandable for users

  • Yes, this was actually proposed by @outsidecontext in his wireframes, and it seems to be interesting so I added it.

  • I actually randomly picked plugins from plugins page in option menu

  • Showing the current top recommended plugins to users would be a good idea I guess. I guess we can get these plugins from Available Plugins - MusicBrainz Picard

  • That link will open the plugins page of picard so that users can select their desired plugins

  • Thanks for pointing it out, I think then it would be better to Introduce both features in Wizard. But then would it be outside the scope of Wizard (wizard is meant for setting up basic settings for a new user)? @outsidecontext, but making a new user understand about Picard’s most important features is also necessary.

  • I thought Reddit or Discourse would be a great place for getting feedback

Thank you for giving the Idea. For right now wizard is designed to be executed for the first time only, If it is shown every time, by default it will show previously selected setting, If user chooses any new setting it will replace those setting with previous one in the summary page.

Sure, I will be adding more detail to the opening scene since It is an important part of the wizard.

Also thanks for pointing out mistakes in the progress bar, I will be changing it from “%” to “Page out of” as mentioned by @Sophist and @aerozol since the pages in wizard are less.

Thanks for the appreciation and your feedback

As you suggested I will be adding more details and “text” to the wizard making sure it stays short but also delivers the information to the user

I had added “” to make it look simple but now I think it will make user confused when they are writing their custom naming script. since there they need to use “%”
And also I will take care to add some warning for the users about using tack-only tags

I think from the reviews I will drop the plan of showing plugins in the wizard since it will be difficult for a new user to understand plugins in first use.

now I think It will be better to show both the features, but in such a way that the wizard sticks to its main idea.

Sure, I will make sure to add that

Thank you for your suggestion! Expanding the explanations of settings on each screen to provide more context and understanding for new users is indeed a great idea. It would help users make more informed decisions about their options and better understand how Picard operates. Additionally, your proposal for managing multiple screens and allowing users to navigate directly to specific sections is a thoughtful solution to keep the wizard user-friendly, especially for those revisiting it.

Whilst there is nothing wrong with any detailed review comments, perhaps it might be useful just to remind people that this is at least as much about the BIG picture of whether:

  • Wizards like this help or hinder? And when and how should they be shown?
  • What wizards should we have? And what broad functionality should they cover?
  • What broad-brush steps should each wizard have?

(In my experience, detailed review comment on actual and detailed proposals are the easy bit of UI discussions. Coming up with a good overall approach and deciding what should be in it in the first place is the hard bit.)


To me, wizard should suggest naming format based on examples rather that obscure percent language.
Music file locations could be detected and suggested.


I don’t disagree that such a wizard / tutorial could add value, but I believe that it is a much more complex undertaking.

My first question would be, “whose preferred workfow should provide the basis for the wizard?” For example, you don’t use the built in file browser (or even have it displayed / enabled in your mockup) and prefer to drag ‘n’ drop from a separate system file browser window, whereas I use the built in browser exclusively. Further, the workflow recommended to be used for retrieving the release information from MusicBrainz (e.g. “Cluster & Lookup”, “Scan” or “Manual Lookup”) depends on the existing file structure and naming (that can be used to parse out things like artist, album and track), and the quality of the existing metadata. Should there be three (or more) different wizards and allow the user to select, or should there only be one, and if only one, which one? Or should there be different paths within the same wizard depending on the results of an action, for example performing a subsequent “Scan” if an initial “Cluster & Lookup” didn’t yield the desired results?

Anyway, that’s another discussion for another day, and I don’t mean to derail this topic.

Sorry, but I’m confused. What is the difference between the first and third checkbox?

Regardless of which, I still believe that there has to be enough text information to ensure that the user is able to make an informed decision as to the option that they are selecting. I actually view a tutorial as more of a step-by-step explanation of the process to follow, more in line with your proposed “new user walkthrough wizard” than this “setup wizard”.

Perhaps the wizard should run automatically the first time Picard is started (and there is no existing configuration file), with the option to re-run it via an item under the “Help” section of the main menu bar?

To address your concern about the amount of text displayed, perhaps the “onboarding” information could be hidden on subsequent runs of the wizard, leaving only the title of the option being set (although I’m not sure I like that idea because it would be essentially the same as the existing option setting screens).


@nullhawk - do you use Picard yourself?

As @rdswift noted, users of Picard all do things in very different ways. Personally I think a “first run” wizard should keep things real simple. Talking of Plugins and AcoustID is more for the advanced and later use. I looked at that wizard and was confused.

Don’t drown a noobie in complexities. :slightly_smiling_face:

For example - you have a section on “file naming convention” but forgot to allow the “don’t rename” option that people like me use. I use Picard to write tags, not rename or move files.

I think you maybe need to do a bit of a survey on “How do you use Picard?” and “What feature did you wish you knew about on first use?

And don’t make the userguide an afterthought on the last page. That needs to be loud and proudly shouted about as so many people seem to miss that.