Skip to content

Commit

Permalink
update README for version 0.1.0 release
Browse files Browse the repository at this point in the history 
It is time to release.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
  • Loading branch information
@takaswie
takaswie committed Apr 19, 2023
1 parent 7c0f3a9 commit a177abc
Showing 1 changed file with 218 additions and 122 deletions.
340 changes: 218 additions & 122 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/alsa-project/snd-firewire-ctl-services/releases/tag/snd-firewire-ctl-services%2Fv0.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 <https://en.wikipedia.org/wiki/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)
Expand All @@ -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 `<crates.io>`_
as well.

* `alsa-ctl-tlv-codec <https://crates.io/crates/alsa-ctl-tlv-codec>`_
* `ieee1212-config-rom <https://crates.io/crates/ieee1212-config-rom>`_
* `ta1394-avc-general <https://crates.io/crates/ta1394-avc-general>`_
* `ta1394-avc-audio <https://crates.io/crates/ta1394-avc-audio>`_
* `ta1394-avc-stream-format <https://crates.io/crates/ta1394-avc-stream-format>`_
* `ta1394-avc-ccm <https://crates.io/crates/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 `<crates.io>`_ as well.

* `firewire-bebob-protocols <https://crates.io/crates/firewire-bebob-protocols>`_
* `firewire-fireworks-protocols <https://crates.io/crates/firewire-fireworks-protocols>`_
* `firewire-oxfw-protocols <https://crates.io/crates/firewire-oxfw-protocols>`_
* `firewire-dice-protocols <https://crates.io/crates/firewire-dice-protocols>`_
* `firewire-digi00x-protocols <https://crates.io/crates/firewire-digi00x-protocols>`_
* `firewire-tascam-protocols <https://crates.io/crates/firewire-tascam-protocols>`_
* `firewire-motu-protocols <https://crates.io/crates/firewire-motu-protocols>`_
* `firewire-fireface-protocols <https://crates.io/crates/firewire-fireface-protocols>`_

* The other crates are released under GNU General Public License Version 3.

Dependencies
============

* Rust programming language <https://www.rust-lang.org/>
* Cargo
* glib `<https://developer.gnome.org/glib/>`_
* libhinawa v2.5 or later `<https://github.com/alsa-project/libhinawa>`_
* libhitaki v0.2 or later `<https://github.com/alsa-project/libhitaki>`_
* alsa-gobject v0.3 or later `<https://github.com/alsa-project/alsa-gobject/>`_

* The library crates enumerated in `License` section are downloaded from `<crates.io>`_ 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 <https://doc.rust-lang.org/cargo/commands/cargo-install.html>`_.

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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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 <https://github.com/alsa-project/snd-firewire-ctl-services>`_.

License
=======

* Some library crates are released under MIT license. They are available in `<crates.io>`_
as well.

* `alsa-ctl-tlv-codec <https://crates.io/crates/alsa-ctl-tlv-codec>`_
* `ieee1212-config-rom <https://crates.io/crates/ieee1212-config-rom>`_
* `ta1394-avc-general <https://crates.io/crates/ta1394-avc-general>`_
* `ta1394-avc-audio <https://crates.io/crates/ta1394-avc-audio>`_
* `ta1394-avc-stream-format <https://crates.io/crates/ta1394-avc-stream-format>`_
* `ta1394-avc-ccm <https://crates.io/crates/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 `<crates.io>`_ as well.

* `firewire-bebob-protocols <https://crates.io/crates/firewire-bebob-protocols>`_
* `firewire-fireworks-protocols <https://crates.io/crates/firewire-fireworks-protocols>`_
* `firewire-oxfw-protocols <https://crates.io/crates/firewire-oxfw-protocols>`_
* `firewire-dice-protocols <https://crates.io/crates/firewire-dice-protocols>`_
* `firewire-digi00x-protocols <https://crates.io/crates/firewire-digi00x-protocols>`_
* `firewire-tascam-protocols <https://crates.io/crates/firewire-tascam-protocols>`_
* `firewire-motu-protocols <https://crates.io/crates/firewire-motu-protocols>`_
* `firewire-fireface-protocols <https://crates.io/crates/firewire-fireface-protocols>`_

* The other crates are for runtime and released under GNU General Public License Version 3.

Dependencies
============

* Rust programming language <https://www.rust-lang.org/> v1.65 or later.
* Cargo
* glib `<https://developer.gnome.org/glib/>`_
* libhinawa v2.5 or later `<https://github.com/alsa-project/libhinawa>`_
* libhitaki v0.2 or later `<https://github.com/alsa-project/libhitaki>`_
* alsa-gobject v0.3 or later `<https://github.com/alsa-project/alsa-gobject/>`_

* The library crates enumerated in `License` section are downloaded from `<crates.io>`_ 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 <https://doc.rust-lang.org/cargo/commands/cargo-install.html>`_.

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 <https://crates.io/crates/tracing>`_ and
`tracing-subscriber <https://crates.io/crates/tracing-subscriber>`_ crates.

Supported protocols
===================
Expand All @@ -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 <https://crates.io/crates/tracing>`_ and
`tracing-subscriber <https://crates.io/crates/tracing-subscriber>`_ crates.

Design note
===========

Expand Down

0 comments on commit a177abc

Please # to comment.