Yoshimi documentation

[Folderol]

Recently I've been going through the Advanced Reference Manual with the help of one of Yoshimi's helpers. This is a PDF file. There were a disappointing number of errors and sections that were out of date, but it is now pretty close to completion.

However, it occurred to me that maybe we should change the layout with regard to the various topics/sections. At the moment these more-or-less just run in a continuous sequence through the pages. In one place that I can think of, there are three quite separate short topics on the same page. On the other hand there are a few that take up two pages.

I'm wondering if (as it is a manual) each topic should start on a new page. On the down side, there would be some taking only about a quarter of a page, but this wouldn't make the file size any greater. However, I've a feeling it would make it easier to keep track of where you were.

What do people here think?

[Drew Stephenson]

As a non-synth user I'd be happy to cast a semi-professional eye over it if you'd like?
Making technical stuff easily digestible has been a good part of my job over the last couple of decades.

[alexis]

From the peanut gallery - for better or worse I think many people will CTRL-F to find a word in the doc, or failing that then glance through the index or TOC. With those tools, the spacing of topics between pages may not be all that important as to spend a lot of time on.

[Folderol]

That's a very kind offer Drew.
If you (or anyone else) would like to take a look the link is here:

https://github.com/Yoshimi/yoshimi-doc/ ... manual.pdf

[The Elf]

I'd prefer dividing white spaces in a a document to keep sections tidy. As you say, it makes little difference to the size of the file.

[alexis]

Looking through it a bit - I'd recommend avoiding page breaks within a section whenever possible for those that want to print (virtually, or hard copy), but I feel multiple sections on a page are fine otherwise.

[ajay_m]

Ok, well, this'll be a relatively long post, apologies.
First of all, I'm a senior software engineer with long-term experience in both writing and reading documentation.

I have never really looked at Yoshimi until now, so I also want to apologise if anything I say here is incorrect as a result of this; but as a newbie I can also give you a fresh perspective perhaps.

Firstly I want to say, this is clearly a complex and incredible piece of work and I salute the people who have laboured hard to bring this to the community, as an open source project. This is truly the spirit of collaboration on which the internet was first founded.

Now I am going to say some things which might sting a bit. I have been on the receiving end of constructive criticism myself and I know the immediate reaction is to feel defensive; it's your baby, you've put hundreds, or thousands of hours work into it, how *dare* someone express less than undying appreciation.

So please accept these comments in the spirit of constructive criticism. I really do appreciate how much work went into this project.

Firstly, you need to step back from manuals and think about personas (or personae if you want to be truly pedantic). Who exactly is going to pick up this manual and read it?. Why?. What sort of background do they have?

Let me take myself as an example: Obviously everyone will be different.
I am technically experienced and I do have Linux experience
I have a lot of experience in audio software in Windows, but none in Linux, though I am aware conceptually of the fundamental subsystems (Jack/ALSA) but I have never configured either of these
I am interested in Yoshimi because of this thread but I haven't heard any example patches (yet)
I have a bunch of Raspberry Pi's of various capabilities sitting on the shelf
I know how to get Raspbian up and running and get a machine running headless, but I don't know how to configure the audio subsystem or install Yoshimi.

Now let's set aside people who already run Yoshimi. For those people, your manual is perfectly adequate. They just need to look up detailed bits of functionality - they already know how to use the product.

So the audience we are looking at is the huge number of people who *might* use Yoshimi but don't know where to start. Let's assume that since it only runs on Linux, they're going to have to use a Raspberry Pi. Yes, a vanishingly rare number of these people might have a Linux PC available or they might want to try and grapple with a virtual machine - but this is highly unlikely, and probably doesn't work very well anyway for realtime audio.

So your audience is:- People who have (or will purchase) a RPi to run Yoshimi and may or may not know anything about Linux etc.

Now let's go back to 'the manual'. Why should there be one manual?. Why not several?. For people who know Yoshimi, fine, you're done, you have a manual. It's big and intimidating and has some flaws - I'll come to that in a sec - but it's comprehensive and nothing a text search won't fix when it comes to finding info.

Would I find 'the manual' useful?. Well, no. Think about what newcomers like me need.

Will the Rpi3 on my shelf with 1G be powerful enough?. If not, what do I need?. Is there a tradeoff e.g can have N voices with an RPi3 and M with an RPi5 etc?.

What is Yoshimi capable of?. Just an overview. I can see there appear to be three synth engines in there. Can you explain the architecture perhaps with a simple block diagram? (apologies if that's in the manual somewhere but it's sure not on page 1). Where can I hear some patches (Soundcloud?)

How do I get started. Link me to the RPi pages for getting an RPi up and running and assume I'll do this headless. 99% I already have a laptop or PC and a network so I'll share the keyboard and display with the RPi - that's the 'happy path' everyone will go down because it's the cheapest.

I'll presumably need some kind of audio output device on the RPi. What are my options?

Once I have the headless RPi running, walk me through getting the audio subsystem working - and tested - there ought to be a simple way for me to get a 'bong' out of the audio out before I go anywhere near Yoshimi.

Now I need to also get MIDI in working. How do I do that?. What are my options?. I probably have a keyboard plugged into my PC. How do I get MIDI out of the PC and into the RPi?. If you don't explain this then that's what the author of "Zen and the art of motorcycle maintenance" calls a 'gumption trap'. A stripped screw in his case. You just go 'er no, too complicated'.

So far so good. NOW I'm ready to install Yoshimi. Walk me through this and then pick me some patches - show me how to select them - and let me just have a play with some of the best sounds you have - I don't want to learn about programming or anything at this stage.

Now THIS manual is quite separate isn't it?. It's something I probably won't need again, but I sure need it to get started and become a Yoshimi user.

Now let's come back to two other things. Firstly, the manual as it stands and secondly the look and feel of the product itself.

The manual as it stands suffers from some common problems with documentation. It states the bleeding obvious without explaining, in many cases. A randomly-chosen example is the discussion on 'extended program change' (I think this was the term, don't have the page up in front of me at present). It's obvious you check the checkbox to enable it but what exactly does it do?. The concept itself is never discussed as far as I can see. Sure, you're not going to explain 'what is midi?' but anything that might be a little unusual, you should explain or link to somewhere that does.

This problem was neatly lampooned by Joel Spolsky years ago. He called it the "LRF-1194 problem". In his scenario, LRF-1194 support is a feature of the product (this is a fictitious feature). The documentation author can't talk to the developer because the developer is on leave. So they write
"LRF-1194 support. Check the checkbox to enable LRF-1194 support. Clear the checkbox to disable LRF-1194 support". Their job is done and yet, this is useless documentation for the obvious reason I have no idea whatsoever why I should check or uncheck the checkbox.

Another issue is the screen to select audio devices. Why isn't this a dropdown list, thus giving me confidence they are all configured properly?. I don't expect free text here.

Finally we come to the UI. Like most open source projects the best way to describe it non-pejoratively is 'functional but cluttered'. The main screen is simply overwhelming at least on first glance. In fairness a lot of professional products share this. It would be fair to say that the screens on my DM3 mixer aren't exactly beautiful either in many cases, they look cluttered and complex too. But it wouldn't be too difficult to improve this. First of all, skeuomorphic things like button borders went out of fashion about 20 years ago. Just have clean buttons with no borders and use an attractive font that's easy to read. I would like to hope the display is fully scaleable unlike some products (looking at you, NI) and if not, spending a bit of time to enable this so I can resize the screen and still have a natural UI flow would be very useful - for example, a lot of us have vision issues and need bigger fonts/contrast etc (you may well have skins, I haven't looked, sorry).

Have a look at some of the web giants UI standards (Google etc). Come to think of this, is the UI browser-hosted?. If not, why not switch to that. There's no point trying to natively host UI in a custom framework fat client these days - it's 2025!. Let the browser do the heavy lifting.

And why is there a Yoshimi menu. This is definitely not remotely compliant with any known UI design standard. Who knows what might go in there, and it encourages random stuff - leftmost menu is supposed to be File in almost all cases - principal of least surprise and all that stuff.

Anyway - those are my initial thoughts. My curiosity is piqued and I have a 2G RPi4 so I do plan to try and get this running in the next few weeks and will try and provide more intelligent feedback at that point. I do want to say, well done everyone, what an amazing piece of work, so please don't feel hurt by anything I say - they are just opinions and arguable, like any aspect of product design.

[Folderol]

First off, thanks for going to the trouble to look at this.

However... (you were expecting that weren't you?)
Yoshimi comes with a built-in HTML UserGuide that does take a new user fairly gently through the synth, whereas this PDF one is an advanced reference manual, so I think it's safe to make some assumptions.

Also, on a first time start there is a pop-up window that advises you to check various settings and also shows where the User Guide is. The early part of the user guide then also shows you where the Advanced Manual is.

You can get a copy of the user guide here:
https://yoshimi.sourceforge.io/docs/user-guide/

As for Yoshimi itself. I think all of us on the development team are well aware of the complexity that would hit a new user smack in the face, but as you say, it's incredibly complex!

As one of our team commented a while ago on our private list. Paul Nasca initially set out to design a synth who's only priority was the sound it created. Interfaces, Development style etc. were a very late second! I think we're a bit better than that now

Yoshimi has a long history. Including the first 5 years of ZynAddSubFX, before it was forked, that's some 20 years, and the current user interface would still be be recognisable to the earliest users. Also, Zyn files from 2006 until 2010, and all Yoshimi ones from then on will sound exactly the same in the latest version of Yoshimi.

Getting back to the Advanced Reference Manual, you do make some quite valid points, and I'll look through this again with your notes in mind.
... all 315 pages

P.S.
As for hearing it's performance there are a number of examples on the Yoshimi website here:
http://yoshimi.github.io/ (also referenced in the user guide).

Also everything I've posted in the SOS Self Promotion subsection uses Yoshimi - pretty much exclusively.

P.P.S
Yoshimi will run of a P3 fairly well, provided you don't get too excited with the more complex sounds.

[ajay_m]

I am - and I again apologise for this - looking at Yoshimi with utter ignorance which means I've skimmed the manual and that's about it. But on the other hand this is useful because it gives me the perspective of an potential "customer" if you like. Now that sounds crazy since you aren't charging any money directly (though I'm sure donations would, quite rightly, be appreciated). But thinking of potential users as 'customers' I think is the right way to focus documentation - we would call them 'stakeholders' generally. They have 'skin in the game' in that they are potentially interested in what you have built.

So looking at the HTML pages, I still think my comments are not too out of line. I couldn't see a block diagram, which would be very useful to conceptualise the architecture when I'm just 'kicking the tyres', for instance. And, as I said, surely 99% of potential 'customers' are going to use an RPi. Yes, the devs all have linux machines, but in the wider world that's incredibly rare. I work in Linux, yes, but I (and my colleagues) use virtual machines in Azure or under Hyper-V - almost nobody sets up a laptop to directly boot into Linux unless they are really, really hard core and the Venn diagram intersection of 'hard core linux users' and 'people who want to try out Yoshimi' is going to mostly consist of ... you and the lovely folks you work with on this project, I'm afraid.

Hence a blow-by-blow guide to getting an RPi up and running would be probably the 'introductory manual' I'd like to see (and again I apologise if such a thing exists, I was just looking at the link you shared).

Now why I say this also is that with the cost of stuff like little LCD touchscreens and all that, it ought to be possible to bolt all that together into a cool little hardware synth (indeed, there may be such a thing, I don't know), and then a project on Instructables would probably garner quite a bit of interest, since lots of people have 3d printers now and this makes things that would historically have been far too complex to make at home, much easier.

I might indeed have a look at this, since my Pico Pi based sequencer project has hit a problem in that the USB host functionality on that platform is still not terribly robust - the hardware works brilliantly, I have a 16X8 RGB lit set of buttons and an OLED display all in a 3d printed case the size of a paperback book, and this works perfectly but I can't complete the project without robust MIDI support over USB via Micropython and it's just not there yet.

Anyway - keep up the hard work - what a wonderful project this is, I must listen to some of the patches now - definitely has my interest piqued and I will try and find some time over the next few weeks to get it up and running, I have a plugin DAC board for the RPi which I imagine will directly work as an audio out, so should be fairly straightforward I hope.

[Drew Stephenson]

Yoshimi comes with a built-in HTML UserGuide that does take a new user fairly gently through the synth, whereas this PDF one is an advanced reference manual, so I think it's safe to make some assumptions.

I was going to ask this before looking in detail this weekend.
Will bear that in mind.

[James Perrett]

I work in Linux, yes, but I (and my colleagues) use virtual machines in Azure or under Hyper-V - almost nobody sets up a laptop to directly boot into Linux unless they are really, really hard core and the Venn diagram intersection of 'hard core linux users' and 'people who want to try out Yoshimi' is going to mostly consist of ... you and the lovely folks you work with on this project, I'm afraid.

Plus my lad - although he came to Linux via the Raspberry Pi.
...

Now why I say this also is that with the cost of stuff like little LCD touchscreens and all that, it ought to be possible to bolt all that together into a cool little hardware synth (indeed, there may be such a thing, I don't know), and then a project on Instructables would probably garner quite a bit of interest, since lots of people have 3d printers now and this makes things that would historically have been far too complex to make at home, much easier.

You've just described a Yoshimi Pi - although I don't know if Will has published a guide to making one yet so this is the nearest there is.

https://www.soundonsound.com/forum/view ... hp?t=68153

[Folderol]

You've just described a Yoshimi Pi - although I don't know if Will has published a guide to making one yet so this is the nearest there is.

https://www.soundonsound.com/forum/view ... hp?t=68153

I'm reluctant to post a guide for this. I'm very very careful when handling mains voltages, but would have no control over what someone else might do, saying (and quite likely believing) it was from my instructions

Obviously it would be possible to specify using a 5V wall-wart, but that removes two significant useful features: self contained & true Off status.

[James Perrett]

Yoshimi comes with a built-in HTML UserGuide that does take a new user fairly gently through the synth,

Which isn't much good if the user doesn't know where to find it! My lad has been using Yoshimi for 2-3 years now and has only just discovered the user guide after I showed him this thread.

His other comment was that the menus in Yoshimi are annoying. They don't follow normal conventions. He pointed out that every other program that he uses has a Help menu as the rightmost entry on the menu bar. Every other program also has a File menu. Programs that don't follow normally accepted conventions like this are annoying and are less likely to gain users.

[James Perrett]

I would like to hope the display is fully scaleable unlike some products (looking at you, NI) and if not, spending a bit of time to enable this so I can resize the screen and still have a natural UI flow would be very useful - for example, a lot of us have vision issues and need bigger fonts/contrast etc (you may well have skins, I haven't looked, sorry).

Yoshimi is scalable although my lad would prefer each dimension to be scalable individually rather than both scaled at the same time. Newer versions also have themes although he hasn't worked out how to create his own themes. My lad says that the theme-able version hasn't found its way into all the Linux repositories yet and some of the controls look a little strange when enlarged.

[BJG145]

@ajay_m - interesting comments, thanks.

So your audience is:- People who have (or will purchase) an RPi to run Yoshimi and may or may not know anything about Linux etc.

That's exactly where I'm at. RPi 5 arrived the other day but I'm still gathering up the various accessories I've since realised I need for it, like a USB-C power adaptor and micro-HDMI cable. (Sounds like I ought to get a heatsink too?)

Hopefully I'll have the full set later today and I'll start working through Eddie's sudo apt-get install checklist. The only gotcha is that I'm hoping to use it with a Pisound card, and I'm anticipating some head-scratching trying to get that working.

There's a microSD from Pi Hut with Pi Os preinstalled on the way, but I'm wondering if I'd be better off starting with the Pisound's "Patchbox OS". The different Linux builds are a mystery to me.

[BJG145]

(…actually I’d go so far as to say that IMHO the fragmented nature of the Linux Universe with its assorted implementations and approaches is one of the major hurdles and drawbacks compared to Mac or Windows, in terms of getting started…)

[James Perrett]

The only gotcha is that I'm hoping to use it with a Pisound card, and I'm anticipating some head-scratching trying to get that working.

It is very easy to create your own SD cards with the OS on them - I wouldn't bother with buying them ready programmed as there are certain things (like Wifi network and password) that you can specify before programming them which will make your life much easier.

If you want to get started easily then I'd get one of those £5 Hifi Berry clones from Ebay and start with that. Something like

https://www.ebay.co.uk/itm/176346176179

For Midi you can start with any class compliant USB Midi interface. For that matter, you could probably just add a class compliant USB audio interface to get started. My lad claims that he has never had to install a driver for any of his interfaces - he just has to tell the OS which one he wants to use.

[Folderol]

Ho-hum
I go a way for five minutes and all hell breaks loose

Where to start.

Yes, the menu system is rather different. Instead of one long list of unrelated things with an (in my view) inappropriate 'File' heading we have small self-contained topic based ones,

The original split up was done by Cal, and a couple of us then consolidated that. It was essentially fixed about 15 years ago. This is the first time I've seen negative comments about it.
Naming the first one 'Yoshimi' was not my preference, but I've no idea what other title it could have. It's the only menu that is rather non-specific.
Also, the main window is the only one with an actual menu bar. There are two others with tabs - not really the same thing.

Non Linux/UNIX users may not recognise the significance of underscored letters. These are key shortcuts. Hold down the 'Alt' key and hit one of these and it performs the same operation as a mouse click.

Window geometery/resize
The scaling is fixed the way it is because it would be very difficult to get layouts looking sensible otherwise - round knob in particular. Also how would you scale text?
We know that some menu arrows go strange when windows are enlarged. This is down to FLTK itself. We've thought about replacing them with our own menu structures, but it would be a lot of work for very little benefit.

Finally, we make changes slowly when necessary. We are very aware that our user-base can be quite fussy, and would be annoyed by sudden dramatic changes. The most noticeable one we ever made was implementing resizing, and even there, the only major style change was to the file manager - we only did that because the FLTK built-in one was impossible to modify.

We always listen to both new and old users and try to keep the majority happy, but like the old saying:

"When up to your arse in crocodiles it's hard to focus on the original object of draining the swamp."

[Hugh Robjohns]

Non Linux/UNIX users may not recognise the significance of underscored letters. These are key shortcuts. Hold down the 'Alt' key and hit one of these and it performs the same operation as a mouse click.

Erm...Windows uses shortcut letters in much the same way, as, I think, does MacOS.

[Folderol]

Non Linux/UNIX users may not recognise the significance of underscored letters. These are key shortcuts. Hold down the 'Alt' key and hit one of these and it performs the same operation as a mouse click.

Erm...Windows uses shortcut letters in much the same way, as, I think, does MacOS.

I expected MacOS might. I haven't seen Windows for years, and don't remember seeing these then. Still, that's absolutely fine. The more the merrier.

[Drew Stephenson]

Sorry Will, the weekend has rather got away from me. Will try and carve out some time this week.

[merlyn]

And, as I said, surely 99% of potential 'customers' are going to use an RPi. Yes, the devs all have linux machines, but in the wider world that's incredibly rare. I work in Linux, yes, but I (and my colleagues) use virtual machines in Azure or under Hyper-V - almost nobody sets up a laptop to directly boot into Linux unless they are really, really hard core and the Venn diagram intersection of 'hard core linux users' and 'people who want to try out Yoshimi' is going to mostly consist of ... you and the lovely folks you work with on this project, I'm afraid.

That's not my experience. Some people use Windows, some use macOS and some use Linux. I use Linux. Does that make me "really, really hardcore"? I wouldn't have thought so.

To put some numbers on it ... it has been estimated that there are 1.4 billion laptops and desktops on Earth. According to Stat Counter Linux makes up 4.13% of those 1.4 billion. macOS makes up about 14%. Roughly speaking, for every three mac users there is a Linux user. In raw numbers there are about 58 million Linux machines.

It's not a huge number but it's not "really, really hardcore" either.

[lorenzosu]

Hi all new to the SOS forums (but not the website) and not-so-new to Yoshimi
Sorry for the long post, but I am a fan of Yoshimi and love making music with it... including two soundtracks which heavily use it, so I thought I'd chime in and provide my point of view in this discussion.

I will say that I use Yoshimi exclusively on a computer (laptop), so know hardly anything about having it on a RPi

That said, I wanted to chime in about the menu querelle. I must say that for me the underlined shortcut letters immediately provided a cue that those were menus, and while I understand that a 'File' menu is very common in many applications, calling what is currently the 'Yoshimi' menu, which I think is also a bit of a 'signature' if you know a bit of Yoshimi's history, 'file' IMHO wouldn't make much sense.

Yoshimi isn't a text editor nor an office applications, so for example you can load/save very different types of files, and personally I find the possibility to load/save states or load/save instruments via dedicated first-level menus a blessing as it's really fast once you know how it works. In my creative process with Yoshimi I use states a lot, and so quickly being able to load/save them (e.g. including different versions) is really important... Would this be berried in some dialog in a File menu it would make it just less quick and break the flow.

Of course UX is always very personal, so I understand that Yoshimi might be a little unfamiliar and overwhelming, I still find out new things after years using it.
How I see it and use Yoshimi is yes as a software but also as a (musical) instrument... Yes you can pick up a guitar and strum it casually, or bang your fingers on a piano and it will make sound, but to actually 'play' it you need dedication and practice.

Maybe Yoshimi would benefit from some visual (video?) tutorials alongside the detailed manual... I have had this idea of maybe producing some, time (TM) permitting.

Let me also add that comments mentioning 'customers' or in that vein make me respectfully smile... Yoshimi is Free Software which is essentially maintained by one person and has a small but usually very friendly and helpful community who lends a hand based on their passion for the software and the kind of music... I think this needs to be taken into account when debating and communicating about it

[BJG145]

Hi lorenzosu - welcome to SOS!

[lorenzosu]

Hi lorenzosu - welcome to SOS!

Thanks!