Contributing to Zynthian Development backup - Revision history

Wyleu: Wyleu moved page Contributing to Zynthian Development to Contributing to Zynthian Development backup

2025-09-05T16:21:06Z

Wyleu moved page Contributing to Zynthian Development to Contributing to Zynthian Development backup

Wyleu: /* How Do I start writing a ctrldev driver? */

2025-09-05T16:12:05Z

How Do I start writing a ctrldev driver?

Wyleu at 15:57, 5 September 2025

2025-09-05T15:57:57Z

Wyleu: /* So what is an IDE ? */

2025-09-05T15:55:44Z

So what is an IDE ?

Wyleu: /* A Notch Filter */

2025-09-04T03:25:44Z

A Notch Filter

Wyleu: /* And from the actual LV2 site... */

2025-09-04T03:22:31Z

And from the actual LV2 site...

Wyleu: /* So what is LV2? */

2025-09-04T03:21:55Z

So what is LV2?

Wyleu: /* So what is LV2? */

2025-09-04T03:21:26Z

So what is LV2?

Wyleu: /* So what is LV2? */

2025-09-04T03:18:39Z

So what is LV2?

Wyleu: /* How Do I start writing a lv2 component compatible with Zynthian? */

2025-09-04T03:05:36Z

How Do I start writing a lv2 component compatible with Zynthian?

@@ Line 496: / Line 496: @@
 From the github.com/zynthian/zynthian-ui/   you can select insights in the top menu and then Network in the left hand vertical menu. Github will chug away for a little while having a think then show you this, which now features the duo-piano-device branch waiting for me to submit the completion of the code with some more commits and then the pull request which, if successful will result in the branch being merged into testing, and at some later date in stable .  . .
 [[File:Zynthian-ui-networks.png|600px|thumb|center]]
 <br clear=all>
 =So what is LV2?=

← Older revision		Revision as of 15:57, 5 September 2025
Line 1:		Line 1:
−	~~== Contributing to Zynthian==~~
−
−	~~=== What we expect of you ===~~
−
−	We would appreciate you to use the tools we use for developing, as it's a lot easier for coordinating the tasks, having traceability, testing, merging changes and of course, attributing the merit of every fix or improvement.
−
−	~~We use '''git''' as versioning tool and '''github''' as repository server and issue/task tracker: [https://github.com/zynthian Zynthian's Repository Index]~~
−
−	~~If you are a punctual contributor, you should follow this procedure:~~
−
−	* fork the repository
−	* make the changes
−	* test it
−	* make a pull request
−
−	~~When you are a habitual contributor, you will receive write access to the repositories you master and would use development branches instead of forking/pull-requesting.~~
−
−	Also, '''it's a good habit to create a task/issue associated with more relevant changes''', specially if you are a newcomer. In such a way other developers will be informed of your intention of implementing a new feature or fixing a bug and will avoid overlapping efforts, at same time allowing other developer to contribute to your task by adding useful knowledge and alternative approaches.
−
−	~~== A first time developer ==~~
−
−	It is perfect understandable if you are approaching this for the first time, with a burning desire to solve a specific musical dilemma with code. Treat it as an opportunity to learn. It is a process that can, at first, appear overly involved and, perhaps, a little bureaucratic, but there are good reasons for the approach that's taken. It has succeeded to keep track of enormous code bases securely, sometimes in the face of actively hostile actions by others. It is this very characteristic that means that many open source projects operate that way, and may give people an insight into quite what 'open source code visible to all really' means for us.
−	Also this robustness should resolve you of fears about 'doing some damage'. This well walked path of forking a repository, and making a Pull request protects you the community from yourself in an agreed fashion.
−
−
−	~~=== Could you tell me about the codebase? ===~~
−
−	This project, Zynthian, is based. predominately, in the python language with various whirling bits of C & C++ doing the heavily mechanical tasks down in the bowls where life is cheap, and code turns precisely. The python is a much more starter friendly world where you define what you want to do, and this gets translated into the sort of coal one can feed into the boilers down below.
−
−	This code resides and runs within a Debian (https://www.debian.org/) based linux distribution, on a Raspberry Pi of various vintages. A zynth, without sound connections doesn't make a lot of sense so there will be some audio out device at the very least, providing an audio output that can be amplified and played to people, yourself or both.
−
−	~~=== So what kind of thing do people do? ===~~
−
−	~~It's open source. Absolutely whatever they want to do . . .~~
−
−	~~For example.. These are devices that have code written specifically for them....~~
−
−	~~[[Supported MIDI controllers\|Supported_MIDI_controllers]]~~
−
−	Personally I do soundscapes, church bells and cajon enhancement, and much of this built without any direct purchase from the zynthian site. The Hardware designs are up on the site if you want to make your own. You'd probably even get advise on how to do it on the forum if you ask ...
−
−	~~=== So why might you want to write some code for a zynthian? ===~~
−
−	~~Probably to do something with a particular piece of equipment that you want to customise to aid you in your sound based endeavours.~~
−	The output of MIDI based equipment presents it's self easily to a python code base that allows messages to be detected in an orderly fashion and then pretty much any aspect of the zynthian can be modified to obey your will. This has grown up from user dialog within the forum [https://discourse.zynthian.org/ Zynthian Forum]which is an excellent place to start with questions, suggestions and the truly crazy range of things people do with these machines.
−
−	~~Here's the current list of devices...[[Supported MIDI controllers\|Supported_MIDI_controllers]]~~
−
−	~~=== Can I do damage to MY zynthian with the code I write ? ===~~
−
−	~~Yes, absolutely.~~
−	~~With power comes responsibility.~~
−
−	~~But there is an important distinction between hardware and software.~~
−	You can produce an inoperable zynthian with a badly placed code edit, but, you can't actively mechanically damage the machine itself by typing garbage. You simply correct the code fault and the damage its done, or at worst put in your backup ssd and things are good again.
−
−	~~This doesn't mean plugging the output of your 100W amp into the audio input of a zynth isn't going to damage it. It will and that's the world of hardware...~~
−
−	~~It's an important distinction.~~
−
−	~~=== Can I do damage to the whole zynthian code system with the code I write ? ===~~
−
−	No. Your code will be checked by people who control access to the core repository that you get your code from. They will not allow anything into the code base that they don't trust or that doesn't meet house rules about how stuff is written and presented.
−
−
−	~~=== How is code of the zynthian maintained? ===~~
−	You can log onto a zynthian itself as the root user if you have the password (opensynth), but you might well change it on a performance machine. (You may wish to avoid developing on your performance machine!) People will find it very amusing to log onto your machine pre or during performance if they can, and if you don't change the password....
−
−	~~[[File:A-terminial-sshing.png\|600px\|center\| An ssh terminal from a host computer (not necessarily yours ....]]~~
−
−
−	You and they (if you haven't changed the password) can, and do pretty much anything you want as it it nothing more or less than a Raspberry Pi of various vintages running an operating system. So you can edit files to your heart's content and very quickly render your zynthian unplayable if you don't know what you are doing.
−	There is an entire Linux world built around what is called a terminal, which contains a command line that you literally type commands into and press enter to get them todo things. zynthian has one of these, and there are code editors that operate entirely around the command line, allowing you to change the contents of files on the machine.
−
−	Here, there is no protection. It's your machine and you can break it as you wish, and whilst you will almost certainly get help on the discourse forum, this is not the sort of activity to indulge in twenty five minutes before your performance. It easy to become the essential technician beloved and feared in equal measure, but probably the first concept to learn is the stable branch...
−
−
−	~~==== So what is a branch? ====~~
−	It's a slightly different version of the code files that a program running on the zynth keeps track of, allowing you to move around between your different versions and accept of reject changes you have made. This all operates under a programme of some renown and reputation called ''git'', which was written by the same bloke who was largely responsible for the Linux code base, which is used to house the Linux code base itself, you are building on the work of giants (... and riban).
−
−	There are many, many introductions to git [https://docs.github.com/en/get-started/getting-started-with-git Getting started with git] and it has a certain reputation for complexity, but it rigorously hangs on to any code it is asked to look after even thou' this can be a mixed blessing if you are as messy as I am. But it can be operated from the command line but it's better to use an IDE (Integrated Development Environment) which makes it all ''push button'', more on this later.
−
−	Git also works peer to peer. This simply mean that rather than some of the older repository managers, every git instance running on a machine has a similar level of importance to every other, so you don't need a running central server to allow you to operate. That is a big feature that you don't appreciate until you DO work with the mega server in the middle with all it's associated limitations.
−	This doesn't mean there isn't a central repository where all the good stuff lives but it does mean that git allows you to make your own little development world where you do no damage to anybody else and you get all the control of being able to set up branches that are differing version of the code and have access to its full history whilst offline.
−
−	~~==== Is Stable the best branch to use? ====~~
−
−	~~Stable is the particular branch of code that is know good and behaves in a fashion that will match the documentation.~~
−	~~It won't be cutting edge, but it will behave itself, precisely as you expect during the performance so this is what you should be initially taking on stage.~~
−
−	~~As of 2024-11-03 Oram is the stable branch which is available from https://os.zynthian.org.~~
−
−	The good news is if you can get enough of a zynthian running to open up its inbuilt webserver, forever known as ''webconf'' in these parts, you can select an option that will allow you to return to the stable state.
−
−	~~[[File:Zynthian software repositories.png\|600px\|center]]~~
−
−	Changing the zynthian-ui (the main zynthian code that controls the touchscreen display and the main audio and midi functionality) branch from stable to another branch and running update will get you to your desired 'branch'. Repeating in reverse to get back to stable version protects your git-committed changes but hides them and returns you to a working stable version.
−
−	This is your protection from your own misdeeds with code. In fact it is sensible to keep at least two uSD cards with a known good stable version on so you can give the zynth a brain change and keep a separate uSD card for your code projects, but if you trash a part of webconf, then you have little or no easy way onto the machine, and you will need your backup... You have been warned!
−
−	~~So now we know how to switch between different branches of code how do we actually set up this new branch?~~
−
−	~~Is there some magic software tool...?~~
−
−	~~==== Who or what is Oram? ====~~
−
−	On 28th September 2024 we released a new stable version: zynthian_2409 which we gave the codename "Oram" to honour [https://en.wikipedia.org/wiki/Daphne_Oram Daphne Oram], a pioneer of electronic sound and music. The ''oram'' git branch is the current stable release version which only changes when there is a ''point release'' (periodic update to deliver feature enhancement and bug fixes) or when there is a ''hotfix'' (urgent bug fixes). This is the version of zynthian that most users should use.
−
−	There is a git branch called ''vangelis'' (named after the wonderful Greek electronic music composer, [https://en.wikipedia.org/wiki/Vangelis Vangelis]) which is used to validate and test further development and bug fixes.
−
−	~~(If we get this right we will finally end up with a branch named after a zynthian user and it will all get needlessly messianic and meta.)~~

	=== So what is an IDE ?===		=== So what is an IDE ?===

@@ Line 111: / Line 111: @@
 (If we get this right we will finally end up with a branch named after a zynthian user and it will all get needlessly messianic and meta.)
-==== So what is an IDE ?====
+=== So what is an IDE ?===
 We could operate all of this using the command line and git commands, but unless you really want to, don't. Use an IDE.

@@ Line 790: / Line 790: @@
 ==A Notch Filter==
+=== The Definition Files===
-Yes, !
+=== The Code components ===
 =====DisthroPluginInfo.h=====

← Older revision		Revision as of 03:22, 4 September 2025
Line 656:		Line 656:

	LV2 is an extensible framework, allowing a program to load a plugin to do some processing. Note that the terms used here are generic on purpose because LV2 allows any type of data to be exchanged between the host and the plugin.		LV2 is an extensible framework, allowing a program to load a plugin to do some processing. Note that the terms used here are generic on purpose because LV2 allows any type of data to be exchanged between the host and the plugin.
		+
		+	== In Summary==

	So there is a clear distinction between the definitions of the facilities which are held in carefully defined definition files and the actual software that accesses the facilities by reading the definition files. This way there is a controlled interaction betwenn the host and the plugin and each can be protected from the vagueries of the other.		So there is a clear distinction between the definitions of the facilities which are held in carefully defined definition files and the actual software that accesses the facilities by reading the definition files. This way there is a controlled interaction betwenn the host and the plugin and each can be protected from the vagueries of the other.

@@ Line 646: / Line 646: @@
 <br clear=all>
 =So what is LV2?=
-[https://en.wikipedia.org/wiki/LV2 From wikipedia...]
+==[https://en.wikipedia.org/wiki/LV2 From wikipedia...]==
 LV2 (LADSPA Version 2) is a set of royalty-free open standards[2] for music production plug-ins and matching host applications. It includes support for the synthesis and processing of digital audio and CV,[3] events such as MIDI and OSC, and provides a free alternative to audio plug-in standards such as Virtual Studio Technology (VST) and Audio Units (AU).
-[https://lv2plug.in/ns/lv2core# And from the actual LV2 site...]
+==[https://lv2plug.in/ns/lv2core# And from the actual LV2 site...]==
 LV2 is an interface for writing audio plugins in C or compatible languages, which can be dynamically loaded into many host applications. This core specification is simple and minimal, but is designed so that extensions can be defined to add more advanced features, making it possible to implement nearly any feature.

← Older revision		Revision as of 03:21, 4 September 2025
Line 656:		Line 656:

	LV2 is an extensible framework, allowing a program to load a plugin to do some processing. Note that the terms used here are generic on purpose because LV2 allows any type of data to be exchanged between the host and the plugin.		LV2 is an extensible framework, allowing a program to load a plugin to do some processing. Note that the terms used here are generic on purpose because LV2 allows any type of data to be exchanged between the host and the plugin.
		+
		+	So there is a clear distinction between the definitions of the facilities which are held in carefully defined definition files and the actual software that accesses the facilities by reading the definition files. This way there is a controlled interaction betwenn the host and the plugin and each can be protected from the vagueries of the other.

	It is a list of definitions that refer back to core definitions and these relationships are maintained in a format called RDF . . .		It is a list of definitions that refer back to core definitions and these relationships are maintained in a format called RDF . . .

@@ Line 648: / Line 648: @@
 [https://en.wikipedia.org/wiki/LV2 From wikipedia...]
 LV2 (LADSPA Version 2) is a set of royalty-free open standards[2] for music production plug-ins and matching host applications. It includes support for the synthesis and processing of digital audio and CV,[3] events such as MIDI and OSC, and provides a free alternative to audio plug-in standards such as Virtual Studio Technology (VST) and Audio Units (AU).
 LV2 is an extensible framework, allowing a program to load a plugin to do some processing. Note that the terms used here are generic on purpose because LV2 allows any type of data to be exchanged between the host and the plugin.
 It is a list of definitions that refer back to core definitions and these relationships are maintained in a format called RDF . . .
 ==So what is RDF ?==
 [https://en.wikipedia.org/wiki/Resource_Description_Framework Once more from wikipedia...]

← Older revision		Revision as of 03:05, 4 September 2025
Line 645:		Line 645:

	<br clear=all>		<br clear=all>
		+	=So what is LV2?=
		+	[https://en.wikipedia.org/wiki/LV2 From wikipedia...]
		+	LV2 (LADSPA Version 2) is a set of royalty-free open standards[2] for music production plug-ins and matching host applications. It includes support for the synthesis and processing of digital audio and CV,[3] events such as MIDI and OSC, and provides a free alternative to audio plug-in standards such as Virtual Studio Technology (VST) and Audio Units (AU).
		+
		+	LV2 is an extensible framework, allowing a program to load a plugin to do some processing. Note that the terms used here are generic on purpose because LV2 allows any type of data to be exchanged between the host and the plugin.
		+
		+	It is a list of definitions that refer back to core definitions and these relationships are maintained in a format called RDF . . .
		+	==So what is RDF ?==
		+	[https://en.wikipedia.org/wiki/Resource_Description_Framework Once more from wikipedia...]
		+
		+	The Resource Description Framework (RDF) is a method to describe and exchange graph data. It was originally designed as a data model for metadata by the World Wide Web Consortium (W3C). It provides a variety of syntax notations and formats, of which the most widely used is Turtle (Terse RDF Triple Language).
		+
		+	It describes objects and the relationships between them . . .
		+
		+	RDF represents information using semantic triples, which comprise a subject, predicate, and object. Each item in the triple is expressed as a Web URI. Turtle provides a way to group three URIs to make a triple, and provides ways to abbreviate such information, for example by factoring out common portions of URIs. For example, information about Huckleberry Finn could be expressed as:
		+
		+	<http://example.org/books/Huckleberry_Finn>
		+	<http://example.org/relation/author>
		+	<http://example.org/person/Mark_Twain> .
		+
		+	In the zynthian plug in world it's primarily about the definition, allocation and mapping of audio and midi ports and parameters in the zynthian world to parameters provided by the LV2 plugin we are exchanging data with.
		+
		+	But first you establish some prefixes so you aren't typing out URL all the time...
		+	Here the classes that are defined by lv2 are specified ( follow the link)
		+	and similarly DOAP defines structure for a software project, and SPDX is the software package data exchange. Thus a set of definitions are described that can be understood by humans ( to a certain extent) and machines (VERY specifically)
		+
		+
		+	@prefix lv2: <http://lv2plug.in/ns/lv2core#>.
		+	@prefix doap: <http://usefulinc.com/ns/doap#>.
		+	@prefix spdx: <http://spdx.org/rdf/terms#>.
		+
		+	Then you use these prefixes to define the relationships we are concerned with...
		+
		+	The 'a' is an atom. More news as I get it. . .
		+
		+	<http://example.org/lv2/wikipediaexample/silence>
		+	a lv2:Plugin;
		+	lv2:binary <silence.so>;
		+	doap:name "Silence";
		+	doap:license spdx:GPL-3.0-or-later;
		+	rdfs:comment "This is an example plugin that includes an example plugin description."
		+
		+	lv2:port [
		+	a lv2:AudioPort, lv2:OutputPort;
		+	lv2:index 0;
		+	lv2:symbol "output";
		+	lv2:name "Output";
		+	].
		+
		+
	=== How Do I start writing a lv2 component compatible with Zynthian? ===		=== How Do I start writing a lv2 component compatible with Zynthian? ===