Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@gvnnz
gvnnz committed Feb 26, 2024
1 parent 65ec50d commit 723038b
Show file tree
Hide file tree
Showing 20 changed files with 62 additions and 54 deletions.
36 changes: 15 additions & 21 deletions src/html/documentation/action-editor.pug
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ block content
h2 General interactions

p.
All the widgets work the same way: you manage them with the mouse and you add, remove or shift the actions by clicking on them.
All widgets work the same way: you manage them with the mouse and you add, remove or shift the actions by clicking on them.

table.table
tr
Expand All @@ -44,6 +44,12 @@ block content
#[span.code left click] + drag on action
td.
move the action or resize it
tr
td.
#[span.code Ctrl] + mouse wheel scroll (Windows and Linux)<br>
#[span.code Cmd] + trackpad scroll (macOS)
td.
zoom in/out

p.
The #[strong zoom buttons] #[img.inline(src='images/docs/zoom-buttons.png' alt='Zoom buttons' title='Zoom buttons')] in the upper right corner of the window allow to magnify or reduce the view of all the widgets. The #[strong grid tool] #[img.inline(src='images/docs/giada-action-editor-snap-grid.png' alt='Grid tool' title='Grid tool')] shows a visual grid over the beat cells; the small check button on the right enables snapping.
Expand All @@ -58,11 +64,9 @@ block content
li.
key press, key release, sample kill — through the #[strong start/stop] widget;
li.
volume — through the #[strong volume envelope] widget;
li.
MIDI notes — through the #[strong piano roll] widget;
velocity — through the #[strong velocity] widget;
li.
MIDI velocity — through the #[strong velocity] widget.
MIDI notes — through the #[strong piano roll] widget.

h2 Start/stop widget

Expand All @@ -71,7 +75,6 @@ block content
p.
The Start/stop widget works only for #[strong Sample channels] set in #[strong oneshot mode] (see #[a(href='documentation-channels-and-samples') Channels and Samples] chapter); if you open the editor for a Sample channel set in #[strong loop mode], the widget will be disabled. Actions are represented in different ways:


ul
li
p.
Expand All @@ -81,20 +84,20 @@ block content
#[strong Key release] #[img.inline(src='images/docs/action-keyrel.png' title='Action keyrel' alt='Action keyrel')] — a single key release;
li
p.
#[strong Kill chan] #[img.inline(src="images/docs/action-killchan.png" title="Action kill chan" alt="Action kill chan")] — a sample break, usually recorded live with #[span.code shift+(key)];
#[strong Stop sample] #[img.inline(src="images/docs/action-killchan.png" title="Action kill chan" alt="Action kill chan")] — a sample break, usually recorded live with #[span.code shift+(key)];
li
p.
#[strong Composite action] #[img.inline(src='images/docs/action-composite.png' title='Composite action' alt='Composite action')] — it represents the combination of a #[em key press] + #[em key release] and it's available only for channels set to #[strong oneshot press] mode #[img.inline(src='images/docs/mode_loopd.png' tile='Oneshot press' alt='Oneshot press')]. It shows the #[em duration] of the key pressure and you can resize it by dragging the edges.

p.
The #[strong action type selector] #[img.inline(src="images/docs/action-type.png" alt="Action type selector" title="Action type selector")] changes the action type you would add by left-clicking on an empty area.
The #[strong action type selector] #[img.inline(src="images/docs/action-type.png" alt="Action type selector")], located on the top-left corner of the Action Editor window, changes the action type you would add by left-clicking on an empty area.

h2 Volume Envelope widget
h2 Velocity widget

p.
#[img(src="images/docs/volume-envelope-widget.png" title="Volume Envelope widget" alt="Volume Envelope widget")]
#[img(src="images/docs/velocity-widget.png" title="Velocity widget" alt="Velocity widget")]
p.
The Volume Envelope widget handles volume changes. It ranges from 0 (bottom, silence) to 1 (top, full amplitude). Click on the first or last point to erase the envelope completely.
Available for both #[strong Sample channels] and #[strong MIDI channels], the Velocity widget lets you change the overall volume of an action. On MIDI channels, values range from 0 (silent) to 127 (maximum loudness) to match the expected value range defined by the MIDI protocol. Each action has its corresponding point in the velocity widget.

h2 Piano Roll widget

Expand All @@ -103,13 +106,4 @@ block content
p.
Available only for #[strong MIDI channels], the Piano Roll widget handles MIDI notes. It represents the full set of 128 notes (0-127) with 11 octaves ranging from C-1 (or C0) to G9 (or G10).
p.
Starting from version 0.13.4 the piano roll editor is able to cope with wrong MIDI events, such as two Note On next to each other. We call them #[strong orphaned MIDI events] and they look like an empty rectangle #[img.inline(src='images/docs/action-orphaned.png' alt='Orphaned MIDI event' title='Orphaned MIDI event')] with fixed width.
p.
You can't do much with an orphaned MIDI event, except for deleting it by right clicking on it. Useful to clean up a MIDI mess.

h2 Velocity widget

p.
#[img(src='images/docs/velocity-widget.png' title='Velocity widget' alt='Velocity widget')]
p.
Available only for #[strong MIDI channels], the Velocity widget lets you change the overall volume of the MIDI note. Values range from 0 (silent) to 127 (maximum loudness). Each point in the velocity widget matches the corresponding note in the piano roll editor.
The piano roll editor is able to cope with wrong MIDI events, such as two Note On next to each other. We call them #[strong orphaned MIDI events] and they look like an empty rectangle #[img.inline(src='images/docs/action-orphaned.png' alt='Orphaned MIDI event' title='Orphaned MIDI event')] with fixed width. You can't do much with an orphaned MIDI event, except for deleting it by right clicking on it. Useful to clean up a MIDI mess.
2 changes: 2 additions & 0 deletions src/html/documentation/channels-and-midi.pug
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,8 @@ block content
p #[strong Setup MIDI input] — binds MIDI events to channel. More information in the #[a(href='documentation-midi-input-management') MIDI input management] chapter;
li
p #[strong Setup MIDI output] — enables MIDI output from this channel. More information in the #[a(href='documentation-midi-output-management') MIDI output management] chapter;
li
p #[strong Edit routing] — allows to tweak some input and output properties such as panning, volume, ...;
li
p #[strong Rename] — changes the channel name;
li
Expand Down
3 changes: 3 additions & 0 deletions src/html/documentation/channels-and-samples.pug
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,9 @@ block content
li
p.
#[strong Setup MIDI output] — enables MIDI output from this channel, see #[a(href='documentation-midi-output-management') MIDI output management];
li
p.
#[strong Edit routing] — allows to tweak some input and output properties such as panning, volume, ...;
li
p.
#[strong Edit sample] — opens the #[a(href='documentation-sample-editor') Sample Editor];
Expand Down
7 changes: 3 additions & 4 deletions src/html/documentation/configuration.pug
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,14 +128,13 @@ block content
ol
li
p.
Linux — #[span.code /home/(your_user)/.giada/langmaps/];

Linux — #[span.code /home/(your_user)/.config/giada/langmaps/];
li
p.
Mac — #[span.code (your_home)/Library/Application Support/Giada/langmaps/];
Mac — #[span.code /Users/(your_user)/Library/Application Support/Giada/langmaps/];
li
p.
Windows — #[span.code langmaps/] folder, alongside the binary file.
Windows — #[span.code C:\Users\(your_user)\AppData\Giada\langmaps\].

p.
Langmap files can be downloaded from #[a(href='https://github.com/monocasual/giada-langmaps') the official repository of Giada langmap files] on GitHub. New translations are welcome! Plese take a look at the #[a(href='https://github.com/monocasual/giada-langmaps#readme') README.md] file if you want to contribute.
2 changes: 1 addition & 1 deletion src/html/documentation/index.pug
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ block content
li
h2
a(href='documentation-save-load-export') Save, load, export
p How to save your works and other interesting options.
p How to save your work and other interesting options.
li
h2
a(href='documentation-configuration') Configuration
Expand Down
4 changes: 2 additions & 2 deletions src/html/documentation/introduction.pug
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ block content
h2 Warnings

p.
Giada is still in a beta stage of development and may lack of some functionalities which could make it hard to use. Please see the #[a(href="https://github.com/monocasual/giada/milestones") milestones] to understand the direction of development. Giada is obviously full of bugs, too. So you are welcome to join our #[a(href="https://github.com/monocasual/giada/discussions") forum] and submit any malfunction or suggestion.
Giada is in a constant stage of development and may lack of some functionalities which could make it hard to use. Please see the #[a(href="https://github.com/monocasual/giada/milestones") milestones] to understand the direction of development. Giada is obviously full of bugs, too. So you are welcome to join our #[a(href="https://github.com/monocasual/giada/discussions") forum] and submit any malfunction or suggestion.
p.
If you want to collaborate with this project, join us on #[a(href='https://github.com/monocasual/giada') GitHub].

Expand Down Expand Up @@ -82,7 +82,7 @@ block content
h2 Problems with the Linux version?

p.
The AppImage package that you can download from this website should just work out of the box. However for the absolute, best, top-notch experience you should also try binaries shipped by the package manager of your favorite distribution. Giada is available on #[a(href="https://packages.debian.org/search?keywords=giada&searchon=names&section=all") Debian], #[a(href="https://packages.ubuntu.com/search?section=all&arch=any&keywords=giada&searchon=names") Ubuntu] and many more.
The AppImage package that you can download from this website should just work out of the box. However for the absolute, best, top-notch experience you should also try binaries shipped by the package manager of your favorite distribution. Giada is available on #[a(href="https://packages.debian.org/search?keywords=giada&searchon=names&section=all") Debian], #[a(href="https://packages.ubuntu.com/search?section=all&arch=any&keywords=giada&searchon=names") Ubuntu], #[a(href="https://flathub.org/apps/com.giadamusic.Giada") Flathub] and many more.

h2 Problems with the macOS version?

Expand Down
4 changes: 2 additions & 2 deletions src/html/documentation/live-sampling.pug
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ block content
User guide<br>Live sampling.

p.
Giada gives you the ability to record anything coming in from your soundcard thanks to its live sampler and the master input channel. Configure your device in the #[a(href="documentation-configuration") Configuration panel] first, then turn up the knob of the #[strong input volume] #[img(src="images/docs/gui_inputmeter.png" alt="The input peakmeter" class="inline")] in the main window.
Giada gives you the ability to record anything coming in from your soundcard thanks to its live sampler and the master input channel. Configure your device in the #[a(href="documentation-configuration") Configuration panel] first, then turn up the knob of the #[strong input volume] in the main window.

h2 How to use the live sampler

Expand All @@ -29,7 +29,7 @@ block content
p.
Arm the channel and check the #[strong input monitor] flag in channel drop-down menu. This way you will hear what you're actually playing, previously processed by the plugins stack (if any). If you don't enable the sampler (#[strong input recording button] #[img(src='images/docs/input-recording-button.png' alt='Input recording button' class='inline')] or #[span.code end] key), Giada won't record anything and turns itself into a live effects processor.
p.
You can accomplish the same result by using the #[strong stream linker], the button between the input and the output meter #[img(src="images/docs/input-output-linker.png" alt="Input to output linker" class="inline")] located on the main window. Enable it and you will be able to hear what you"re playing.
You can accomplish the same result by using the #[strong stream linker] #[img(src="images/docs/stream-linker-button.png" alt="Input to output linker" class="inline")], the button located right below the input meter in the main window. Enable it and you will be able to hear what you"re playing.

h2 Record on signal

Expand Down
15 changes: 7 additions & 8 deletions src/html/documentation/midi-output-management.pug
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ block content
#[img(src='images/docs/midi-output-config-regular.png' alt='MIDI output config tool, regular')]

p.
This kind of messages are managed by the dropdown menu shown on the left. If you check #[em enable MIDI output], MIDI messages will be sent outside Giada whenever an action occurs, through the MIDI channel specified with the drop-down menu on the right. With this technique you will be able to control external MIDI hardware or other software as well.
This kind of messages are managed by the tools shown in the picture above. If you check #[em enable MIDI output], MIDI messages will be sent outside Giada whenever an action occurs, through the MIDI channel specified with the drop-down menu on the right. With this technique you will be able to control external MIDI hardware or other software as well.

h3 MIDI lightning messages

Expand All @@ -76,12 +76,11 @@ block content
Giada needs to know what data to send when MIDI lightning occurs. Each hardware producer defines its own set of messages, so we introduce the concept of #[strong midimap files]. A midimap is a JSON-formatted text file where you define what kind of messages you want Giada to send. They reside in your configuration directory, or more precisely:
ul
li.
Linux —
#[span.code /home/(your_user)/.giada/midimaps/];
Linux — #[span.code /home/(your_user)/.config/giada/midimaps/];
li.
Mac — #[span.code (your_home)/Library/Application Support/Giada/midimaps/];
Mac — #[span.code /Users/(your_user)/Library/Application Support/Giada/midimaps/];
li.
Windows — #[span.code midimaps/] folder, alongside the binary file.
Windows — #[span.code C:\Users\(your_user)\AppData\Giada\midimaps\].
p.
Giada will look into those directories on startup. If the files are valid midimap files they will be listed in the #[a(href='documentation-configuration') Configuration window], MIDI section. Pick up the minimap file you want to use in the dropdown menu and you are ready to go.

Expand Down Expand Up @@ -166,9 +165,9 @@ block content
In details:
ul
li.
#[strong MIDI-channel] —the MIDI channel where to output to, in a numeric range of 0-15;
#[strong channel] —the MIDI channel where to output to, in a numeric range of 0-15;
li.
#[strong hex-message] —the actual message to send, in hexadecimal form, 4 bytes long.
#[strong message] —the actual message to send, in hexadecimal form, 4 bytes long.
p.
The hexadecimal message contains a special placeholder for the note. Since each message is customized by the vendor, you have to specify where the byte for the note resides. The placeholder is defined as #[span.code nn]; Giada will replace it on the fly once the key has been configured and grabbed with the MIDI learning tool seen before. Below a couple of illustrative lightning messages:
pre.code.
Expand Down Expand Up @@ -236,7 +235,7 @@ block content
h2 Where do I find midimaps?

p.
We store the full list of midimap files on GitHub in the #[a(href="https://github.com/monocasual/giada-midimaps")] midimap repository. Download the zip archive and uncompress it in the midimap folders seen before.
We store the full list of midimap files on GitHub in the #[a(href="https://github.com/monocasual/giada-midimaps") giada-midimaps repository]. Download the zip archive and uncompress it in the midimap folders seen before.

p.
Pull requests and file submissions are absolutely welcome and encouraged. If you have a MIDI controller whose midimap file is missing, feel free to add it to our collection!
Expand Down
Loading

0 comments on commit 723038b

Please sign in to comment.