Skip to content

Commit

Permalink
Add 2 screenshots, start writing
Browse files Browse the repository at this point in the history
  • Loading branch information
falkTX committed Oct 20, 2019
1 parent 661853a commit bb18b54
Show file tree
Hide file tree
Showing 7 changed files with 133 additions and 5 deletions.
47 changes: 47 additions & 0 deletions BasicConcepts.adoc
@@ -0,0 +1,47 @@

Carla is by design a modular audio plugin host.
This means it will load audio plugins in a modular rather, where each plugin is a module inside a patchbay and you can connect between them and your hardware in order to send signals to the plugins and/or have them generate sound.

In a modular host, the simplest way to achieve sound is by using "generators" (something that either generates sound by itself, or based on user input).

Here is an example of a MIDI keyboard connected to a synth, which is then connected to the output speakers:

image::screenshots/manual/basics_midi_synth.png[]

==== Control Voltage

In modular hosts it is common to have CV (Control Voltage) signals.

These are similar to audio, in that they stream at regular intervals (contrary to events which only happen at specific points in time).
CV are a good option for parameters that require very precise and fast control, as they provide infinite precision (CV changes are sample-accurate and not limited to a specific amount of steps)

==== Carla specifics

In Carla, audio and CV connections have blue color, while events (including MIDI) have red color.
Events are merged into a single port, while audio and CV are separate. For example, stereo audio output consists of 2 independent audio ports.

Audio ports can be patched at will, from any port to any port.
CV is treated similar to audio (because technically it really is), but you are not allowed to connect audio and CV ports together, for safety reasons.
Audio and CV ports are constantly streaming data from one side to the other.
An audio port streams data for a single mono audio channel, while a CV port streams data for a single control/parameter.

Event ports transmit events when they happen (for example, pressing a key on a MIDI keyboard).
All of MIDI and OSC related events are bundled together in a single event port.

==== Engine modes

There are 4 types of engine processing modes in Carla:

- Single-client: (JACK driver only)
Same as Multi-client, except that all JACK ports belong to a single master client.
This is needed when a setup doesn't support multi-client JACK apps, such as LADISH.

- Multi-client: (JACK driver only)
Every single plugin is exposed as a new JACK client. Audio, CV and event ports are registered as needed.

- Continuous Rack:
Plugins are processed in order, from top to bottom.

- Patchbay:
Modular patchbay mode, just like in JACK Multi-client and many other modular applications.
Every plugin gets its own canvas group and ports allowing you to interconnect plugin audio, cv and event ports.
12 changes: 8 additions & 4 deletions Introduction.adoc
@@ -1,10 +1,14 @@

Carla is...
=== About Carla

Carla is a fully-featured modular audio plugin host, with support for many audio drivers and plugin formats.

It has some nice features like transport control, automation of parameters via MIDI CC and remote control over OSC.

=== About the User Manual

The Manual was divided into several sections:
This Manual was divided into several sections:

Introduction:: is the first part of the Manual, we're starting with an overview of the application and mowith a few simple tutorials to get the user hands-on with the synthesizer as fast as possible.
Basic Topics:: is the second part where we start to cover everything from top to bottom. If you're fairly new to Carla, this part should provide you with a comprehensive, yet not overwhelming instruction.
Advanced Topics:: the third part, where we go into more detail and cover things that were skipped in the previous part. More advanced users should benefit from this part, adding depth to their understanding of the
Main Topics:: is the second part where we start to cover everything from top to bottom. If you're fairly new to Carla, this part should provide you with a comprehensive, yet not overwhelming instruction.
// Advanced Topics:: the third part, where we go into more detail and cover things that were skipped in the previous part. More advanced users should benefit from this part, adding depth to their understanding of the
21 changes: 21 additions & 0 deletions Makefile
@@ -0,0 +1,21 @@

all: build

build: html resources

html: ../manuals/carla.html
resources: $(patsubst %,../%,$(wildcard screenshots/manual/*.png))

../manuals/carla.html: *.adoc
asciidoc \
--no-header-footer \
--out-file=../manuals/carla.html \
Manual.adoc

../screenshots/manual/%.png: screenshots/manual/%.png
cp -v $< $@

clean:

watch:
while true; do make; sleep 1; done
5 changes: 4 additions & 1 deletion Manual.adoc
Expand Up @@ -4,7 +4,10 @@
== Introduction
include::Introduction.adoc[]

== Basic Topics
=== Basic Concepts
include::BasicConcepts.adoc[]

== Main Topics

=== User Interface
include::UserInterface.adoc[]
53 changes: 53 additions & 0 deletions UserInterface.adoc
@@ -1,2 +1,55 @@
=== Main Window

When you run Carla you'll be presented with this window:

image::screenshots/manual/ui_main.png[]

You can see some familiar elements from other applications, like the menu-bar and tool-bar.
Then you have a side-panel where you will find an integrated filesystem browser (with user bookmarks) and transport controls.

The bigger central area is the working space.
Here you find the "Rack" where all plugin instances will be shown, the "Patchbay" where you can make connections between the plugins and hardware, and "Logs" where debug or warning messages are logged.

Please note that, under some systems or circunstances, these tabs will not be present.
When Carla runs as a plugin or under Windows platform, the "Logs" is not visible.
And when Carla runs as "Carla-Rack" plugin, the "Patchbay" tab is not shown.

The toolbar buttons can also be different depending on the occasion.
For example, "Save" is not available when running as a plugin, since it is the host responsibility to do that instead.

==== Menus

===== File

In the file menu you can start your project/session from scratch, open existing ones, save and quit/close Carla.

==== Engine

In the engine menu you have the chance to start and stop the audio engine.

In the future it is planned to add a direct shortcut to engine settings here.

==== Plugin

In the plugin menu is where you find the action to add new plugins into the session.
You can also remove all plugins from this menu, and trigger a few action to all of them at once (for convenience).

==== Canvas

In the canvas menu you find options related to the patchbay canvas view.
These are to refresh, set zoom level and export the canvas as an image.

When running Carla's engine in "Patchbay" mode, you will also find here a "Show Internal" and "Show External" switch.
This allows to connect the internal patchbay graph into external devices, such as MIDI keyboards and other JACK clients.
Using the "Show External" switch is how you usually will setup your MIDI devices.

==== Settings

In the settings menu you can find the action to open Carla's settings, as well as a few on/off switches for what to show on screen.
By default everything is visible, but you can hide stuff if you prefer.

==== About

In the about menu you can open Carla's about dialog.

In the future it is planned to have useful links here.
Binary file added screenshots/manual/basics_midi_synth.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added screenshots/manual/ui_main.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit bb18b54

Please sign in to comment.