From a177abc01501a36533aff259b934f7543008eb33 Mon Sep 17 00:00:00 2001 From: Takashi Sakamoto Date: Wed, 19 Apr 2023 17:18:53 +0900 Subject: [PATCH] update README for version 0.1.0 release It is time to release. Signed-off-by: Takashi Sakamoto --- README.rst | 340 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 218 insertions(+), 122 deletions(-) diff --git a/README.rst b/README.rst index c40507da0..52cd4c362 100644 --- a/README.rst +++ b/README.rst @@ -2,18 +2,31 @@ snd-firewire-ctl-services ======================== -2023/04/16 +2023/04/19 Takashi Sakamoto Introduction ============ -This project is a sub project in Advanced Linux Sound Architecture a.k.a ALSA, -to produce userspace service daemon for Audio and Music units on IEEE 1394 bus, -supported by drivers in ALSA firewire stack. +This project is a sub-project within Advanced Linux Sound Architecture a.k.a ALSA, aimed to provide +user space service programs for Audio and Music units connected to IEEE 1394 bus, supported by +drivers in ALSA firewire stack. -Executables (binary crates) -=========================== +The latest release is +`version 0.1.0 `_. + +The service programs are designed to operate digital signal processing function in the audio and +music units connected to IEEE 1394 bus. The service programs work as +`message broker `_. ALSA control and sequencer +applications are available as an end to communicate to the service programs. The audio and music +units in IEEE 1394 bus is the opposite end. The service programs receives messages from both +ends, then translates and convert the messages to send to the opposite end. The internal design of +the programs are illustrated in ``Design note`` section. + +Executables for service programs +================================ + +The project provides the following service programs in the form of Rust binary crates: snd-firewire-digi00x-ctl-service For sound card bound to ALSA firewire-digi00x driver (snd-firewire-digi00x) @@ -32,98 +45,19 @@ snd-dice-ctl-service snd-fireface-ctl-service For sound card bound to ALSA fireface driver (snd-fireface) -License -======= - -* Some library crates are released under MIT license. They are available in ``_ - as well. - - * `alsa-ctl-tlv-codec `_ - * `ieee1212-config-rom `_ - * `ta1394-avc-general `_ - * `ta1394-avc-audio `_ - * `ta1394-avc-stream-format `_ - * `ta1394-avc-ccm `_ - -* Some library crates for protocol implementation are released under GNU Lesser General - Public License v3.0 or later with respect to clause for reverse engineering. They are - available in ``_ as well. - - * `firewire-bebob-protocols `_ - * `firewire-fireworks-protocols `_ - * `firewire-oxfw-protocols `_ - * `firewire-dice-protocols `_ - * `firewire-digi00x-protocols `_ - * `firewire-tascam-protocols `_ - * `firewire-motu-protocols `_ - * `firewire-fireface-protocols `_ - -* The other crates are released under GNU General Public License Version 3. - -Dependencies -============ - -* Rust programming language -* Cargo -* glib ``_ -* libhinawa v2.5 or later ``_ -* libhitaki v0.2 or later ``_ -* alsa-gobject v0.3 or later ``_ - -* The library crates enumerated in `License` section are downloaded from ``_ when - building. - -How to build -============ - -Build :: - - $ cargo build - -Execute temporarily :: - - & cargo run --bin (the executable name) -- (the arguments of executable) - -All of executables can print help when either ``--help`` or ``-h`` is given as an argument of -command line. Additionally, either ``--log-level`` or ``-l`` is also available for runtime -debugging. For further information, please refer to ``Runtime debugging`` clause. - -Install executables :: - - $ cargo install --path (path to binary crate) +Disclaimer +========== -The runtime crates which provide the executables are listed below: - -snd-firewire-digi00x-ctl-service - ``snd-firewire-digi00x-ctl-service`` crate locates in ``runtime/digi00x`` -snd-firewire-tascam-ctl-service - ``snd-firewire-tascam-ctl-service`` crate locates in ``runtime/tascam`` -snd-fireworks-ctl-service - ``snd-fireworks-ctl-service`` crate locates in ``runtime/fireworks`` -snd-firewire-motu-ctl-service - ``snd-firewire-motu-ctl-service`` crate locates in ``runtime/motu`` -snd-oxfw-ctl-service - ``snd-oxfw-ctl-service`` crate locates in ``runtime/oxfw`` -snd-bebob-ctl-service - ``snd-bebob-ctl-service`` crate locates in ``runtime/bebob`` -snd-dice-ctl-service - ``snd-dice-ctl-service`` crate locates in ``runtime/dice`` -snd-fireface-ctl-service - ``snd-fireface-ctl-service`` crate locates in ``runtime/fireface`` - -The executable is usually installed under ``~/.cargo/bin``, while it's possible to choose the path. -In detail, please refer to -`manual of cargo install `_. - -Uninstall executables :: +The project provides neither GUI programs nor end-user interfaces against expectation of users, - $ cargo uninstall -p (name of runtime crate) +The main motivation of project is to preserve the way (protocol) to operate the audio and music +units in IEEE 1394 bus, which was defined by several vendors. Supported devices ================= -Currently below devices are supported. If you would like to add support for -your device, please contact to developer. +Currently below devices are supported. If you would like to add support for your device, please +contact to developer. * snd-firewire-digi00x-ctl-service @@ -138,7 +72,7 @@ your device, please contact to developer. * Tascam FW-1884 * Tascam FW-1082 * Tascam FW-1804 - * Tascam FE-8 + * Tascam FE-8 (work without ALSA firewire-tascam driver) * snd-fireworks-ctl-service @@ -155,21 +89,29 @@ your device, please contact to developer. * snd-firewire-motu-ctl-service - * MOTU 828 - * MOTU 896 - * MOTU Traveler - * MOTU 828mkII - * MOTU 896HD - * MOTU UltraLite - * MOTU 8pre - * MOTU 4pre - * MOTU AudioExpress - * MOTU 828mk3 (FireWire only) - * MOTU 828mk3 (Hybrid) - * MOTU UltraLite mk3 (FireWire only) - * MOTU UltraLite mk3 (Hybrid) - * MOTU Traveler mk3 - * MOTU Track 16 + * Version 1 models + + * MOTU 828 + * MOTU 896 + + * Register DSP models + + * MOTU Traveler + * MOTU 828mkII + * MOTU 896HD + * MOTU UltraLite + * MOTU 8pre + * MOTU 4pre + * MOTU AudioExpress + + * Command DSP models + + * MOTU 828mk3 (FireWire only) + * MOTU 828mk3 (Hybrid) + * MOTU UltraLite mk3 (FireWire only) + * MOTU UltraLite mk3 (Hybrid) + * MOTU Traveler mk3 + * MOTU Track 16 * snd-oxfw-ctl-service @@ -242,10 +184,174 @@ your device, please contact to developer. * snd-fireface-ctl-service - * Fireface 800 - * Fireface 400 - * Fireface UCX - * Fireface 802 + * Former models + + * Fireface 800 + * Fireface 400 + + * Latter models + + * Fireface UCX + * Fireface 802 + +Restrictions +============ + +Due to a lack of information about the target devices, certain restrictions are unavoidable. +However, we welcome any assistance that can enhance the project. + +* snd-bebob-ctl-service + + * The most of compressor, equalizer, and reverb controls are not available for Focusrite Saffire. + * No control is available for un-coded devices. For example, PrismSound Orpheus is the case. + +* snd-fireworks-ctl-service + + * Some control is not available for Gibson Robot Interface Pack. + +* snd-dice-ctl-service + + * The most of equalizer controls are not available for Focusrite Saffire Pro 24 DSP. + * The most of monitor parameters may not work for Alesis iO 14/26 FireWire. This may come from + firmware version. + * The channel strip dynamics, equalizer, and reverb are not available for Lexicon I-ONIX 810s. + * No control is available for Focusrite Saffire Pro 40 (TCD3070 ASIC). + * No control is available for Solid State Logic Duende Classic and Mini. + +* snd-firewire-digi00x-ctl-service + + * Due to hardware design, the function of DSP can not be configured unless an ALSA PCM + application initiates isochronous communication. + +* snd-firewire-tascam-ctl-service + + * Due to hardware design, most controls are not synchronized to hardware expectedly unless an + ALSA PCM application initiates isochronous communication. + * For console models, any event in control surface is available via port of ALSA Sequencer. The + event is converted to controller event with channel 0 which has the consecutive number as param + and event value. At present, the consecutive number is fixed and not configurable. + +* snd-motu-ctl-service + + * Due to hardware design, most controls, including hardware metering, are not synchronized to + hardware expectedly for Register DSP models unless an ALSA PCM application initiates isochronous + communication. + * Due to hardware design, hardware metering may not work properly for Command DSP models unless an + ALSA PCM application initiates isochronous communication. + * The channel positionss available in the hardware meter is not adequate in all Command DSP + models. + * Sometimes, there may be an issue with initializing Command DSP models for communication. In such + case, the workaround is to simply restart the service program. + * 896 mk3 (FireWire only/Hybrid) is not supported since developer has no change to access to it.. + +* snd-fireface-ctl-service + + * The controls of latter models are not synchronized to any operation by the Remote Control or + the Advanced Remote Control. + +Support +======= + +* If finding any issue, please file it to + `github repository `_. + +License +======= + +* Some library crates are released under MIT license. They are available in ``_ + as well. + + * `alsa-ctl-tlv-codec `_ + * `ieee1212-config-rom `_ + * `ta1394-avc-general `_ + * `ta1394-avc-audio `_ + * `ta1394-avc-stream-format `_ + * `ta1394-avc-ccm `_ + +* Some library crates for protocol implementation are released under GNU Lesser General + Public License v3.0 or later with respect to clause for reverse engineering. They are + available in ``_ as well. + + * `firewire-bebob-protocols `_ + * `firewire-fireworks-protocols `_ + * `firewire-oxfw-protocols `_ + * `firewire-dice-protocols `_ + * `firewire-digi00x-protocols `_ + * `firewire-tascam-protocols `_ + * `firewire-motu-protocols `_ + * `firewire-fireface-protocols `_ + +* The other crates are for runtime and released under GNU General Public License Version 3. + +Dependencies +============ + +* Rust programming language v1.65 or later. +* Cargo +* glib ``_ +* libhinawa v2.5 or later ``_ +* libhitaki v0.2 or later ``_ +* alsa-gobject v0.3 or later ``_ + +* The library crates enumerated in `License` section are downloaded from ``_ when + building by configurations of `Cargo.toml`. + +How to build +============ + +Build :: + + $ cargo build + +Execute temporarily :: + + & cargo run --bin (the executable name) -- (the arguments of executable) + +All of executables can print help when either ``--help`` or ``-h`` is given as an argument of +command line. In the most executables, the first positional argument is the numeric identifier of +sound card in Linux sound subsystem. For further information, please refer to ``Runtime debugging`` +clause. + +Install executables :: + + $ cargo install --path (path to binary crate) + +The runtime crates which provide the executables are listed below: + +snd-firewire-digi00x-ctl-service + ``snd-firewire-digi00x-ctl-service`` crate locates in ``runtime/digi00x`` +snd-firewire-tascam-ctl-service + ``snd-firewire-tascam-ctl-service`` crate locates in ``runtime/tascam`` +snd-fireworks-ctl-service + ``snd-fireworks-ctl-service`` crate locates in ``runtime/fireworks`` +snd-firewire-motu-ctl-service + ``snd-firewire-motu-ctl-service`` crate locates in ``runtime/motu`` +snd-oxfw-ctl-service + ``snd-oxfw-ctl-service`` crate locates in ``runtime/oxfw`` +snd-bebob-ctl-service + ``snd-bebob-ctl-service`` crate locates in ``runtime/bebob`` +snd-dice-ctl-service + ``snd-dice-ctl-service`` crate locates in ``runtime/dice`` +snd-fireface-ctl-service + ``snd-fireface-ctl-service`` crate locates in ``runtime/fireface`` + +The executable is usually installed under ``~/.cargo/bin``, while it's possible to choose the path. +In detail, please refer to +`manual of cargo install `_. + +Uninstall executables :: + + $ cargo uninstall -p (name of runtime crate) + +Runtime debugging +================= + +All executables support an option for log level for debugging. When either ``-l`` or +``--log-level`` is given with log level, they prints verbose logs to standard output. +At present, ``debug`` is just supported for the log level. + +This function is implemented by `tracing `_ and +`tracing-subscriber `_ crates. Supported protocols =================== @@ -271,16 +377,6 @@ Supported protocols * Protocol for former models of Fireface series of RME GmbH * Protocol for latter models of Fireface series of RME GmbH -Runtime debugging -================= - -All executables support an option for log level for debugging. When either ``-l`` or -``--log-level`` is given with log level, they prints verbose logs to standard output. -At present, ``debug`` is just supported for the log level. - -This function is implemented by `tracing `_ and -`tracing-subscriber `_ crates. - Design note ===========