--- web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt 2006/12/20 19:56:43 993 +++ web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt 2007/02/19 19:46:20 1048 @@ -4,7 +4,7 @@ LinuxSampler Developers C. Schoenebeck Internet-Draft Interessengemeinschaft Software Intended status: Standards Track Engineering e. V. -Expires: June 23, 2007 December 20, 2006 +Expires: August 23, 2007 February 19, 2007 LinuxSampler Control Protocol @@ -33,11 +33,11 @@ The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. - This Internet-Draft will expire on June 23, 2007. + This Internet-Draft will expire on August 23, 2007. Copyright Notice - Copyright (C) The Internet Society (2006). + Copyright (C) The Internet Society (2007). @@ -52,9 +52,9 @@ -Schoenebeck Expires June 23, 2007 [Page 1] +Schoenebeck Expires August 23, 2007 [Page 1] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 Abstract @@ -68,140 +68,150 @@ Table of Contents - 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 5 - 2. Versioning of this specification . . . . . . . . . . . . . . . 6 - 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 4. Focus of this protocol . . . . . . . . . . . . . . . . . . . . 8 - 5. Communication Overview . . . . . . . . . . . . . . . . . . . . 9 - 5.1. Request/response communication method . . . . . . . . . . 9 - 5.1.1. Result format . . . . . . . . . . . . . . . . . . . . 10 - 5.2. Subscribe/notify communication method . . . . . . . . . . 12 - 6. Description for control commands . . . . . . . . . . . . . . . 14 - 6.1. Ignored lines and comments . . . . . . . . . . . . . . . . 14 - 6.2. Configuring audio drivers . . . . . . . . . . . . . . . . 14 - 6.2.1. Getting amount of available audio output drivers . . . 15 - 6.2.2. Getting all available audio output drivers . . . . . . 15 + 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 5 + 2. Versioning of this specification . . . . . . . . . . . . . . 6 + 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 + 4. Focus of this protocol . . . . . . . . . . . . . . . . . . . 8 + 5. Communication Overview . . . . . . . . . . . . . . . . . . . 9 + 5.1. Request/response communication method . . . . . . . . . . 9 + 5.1.1. Result format . . . . . . . . . . . . . . . . . . . . 10 + 5.2. Subscribe/notify communication method . . . . . . . . . . 12 + 6. Description for control commands . . . . . . . . . . . . . . 14 + 6.1. Ignored lines and comments . . . . . . . . . . . . . . . 14 + 6.2. Configuring audio drivers . . . . . . . . . . . . . . . . 14 + 6.2.1. Getting amount of available audio output drivers . . 15 + 6.2.2. Getting all available audio output drivers . . . . . 15 6.2.3. Getting information about a specific audio output - driver . . . . . . . . . . . . . . . . . . . . . . . . 15 + driver . . . . . . . . . . . . . . . . . . . . . . . 15 6.2.4. Getting information about specific audio output - driver parameter . . . . . . . . . . . . . . . . . . . 16 - 6.2.5. Creating an audio output device . . . . . . . . . . . 20 - 6.2.6. Destroying an audio output device . . . . . . . . . . 21 - 6.2.7. Getting all created audio output device count . . . . 22 - 6.2.8. Getting all created audio output device list . . . . . 22 - 6.2.9. Getting current settings of an audio output device . . 22 - 6.2.10. Changing settings of audio output devices . . . . . . 24 - 6.2.11. Getting information about an audio channel . . . . . . 25 + driver parameter . . . . . . . . . . . . . . . . . . 16 + 6.2.5. Creating an audio output device . . . . . . . . . . . 20 + 6.2.6. Destroying an audio output device . . . . . . . . . . 21 + 6.2.7. Getting all created audio output device count . . . . 22 + 6.2.8. Getting all created audio output device list . . . . 22 + 6.2.9. Getting current settings of an audio output device . 22 + 6.2.10. Changing settings of audio output devices . . . . . . 24 + 6.2.11. Getting information about an audio channel . . . . . 25 6.2.12. Getting information about specific audio channel - parameter . . . . . . . . . . . . . . . . . . . . . . 26 - 6.2.13. Changing settings of audio output channels . . . . . . 28 - 6.3. Configuring MIDI input drivers . . . . . . . . . . . . . . 29 - 6.3.1. Getting amount of available MIDI input drivers . . . . 30 - 6.3.2. Getting all available MIDI input drivers . . . . . . . 30 + parameter . . . . . . . . . . . . . . . . . . . . . . 26 + 6.2.13. Changing settings of audio output channels . . . . . 28 + 6.3. Configuring MIDI input drivers . . . . . . . . . . . . . 29 + 6.3.1. Getting amount of available MIDI input drivers . . . 30 + 6.3.2. Getting all available MIDI input drivers . . . . . . 30 6.3.3. Getting information about a specific MIDI input - driver . . . . . . . . . . . . . . . . . . . . . . . . 31 + driver . . . . . . . . . . . . . . . . . . . . . . . 31 6.3.4. Getting information about specific MIDI input - driver parameter . . . . . . . . . . . . . . . . . . . 32 - 6.3.5. Creating a MIDI input device . . . . . . . . . . . . . 34 - 6.3.6. Destroying a MIDI input device . . . . . . . . . . . . 35 - 6.3.7. Getting all created MIDI input device count . . . . . 36 + driver parameter . . . . . . . . . . . . . . . . . . 32 + 6.3.5. Creating a MIDI input device . . . . . . . . . . . . 34 + 6.3.6. Destroying a MIDI input device . . . . . . . . . . . 35 + 6.3.7. Getting all created MIDI input device count . . . . . 36 -Schoenebeck Expires June 23, 2007 [Page 2] +Schoenebeck Expires August 23, 2007 [Page 2] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 - 6.3.8. Getting all created MIDI input device list . . . . . . 36 - 6.3.9. Getting current settings of a MIDI input device . . . 37 - 6.3.10. Changing settings of MIDI input devices . . . . . . . 38 - 6.3.11. Getting information about a MIDI port . . . . . . . . 38 + 6.3.8. Getting all created MIDI input device list . . . . . 36 + 6.3.9. Getting current settings of a MIDI input device . . . 37 + 6.3.10. Changing settings of MIDI input devices . . . . . . . 38 + 6.3.11. Getting information about a MIDI port . . . . . . . . 38 6.3.12. Getting information about specific MIDI port - parameter . . . . . . . . . . . . . . . . . . . . . . 39 - 6.3.13. Changing settings of MIDI input ports . . . . . . . . 41 - 6.4. Configuring sampler channels . . . . . . . . . . . . . . . 42 - 6.4.1. Loading an instrument . . . . . . . . . . . . . . . . 42 - 6.4.2. Loading a sampler engine . . . . . . . . . . . . . . . 43 - 6.4.3. Getting all created sampler channel count . . . . . . 44 - 6.4.4. Getting all created sampler channel list . . . . . . . 44 - 6.4.5. Adding a new sampler channel . . . . . . . . . . . . . 44 - 6.4.6. Removing a sampler channel . . . . . . . . . . . . . . 45 - 6.4.7. Getting amount of available engines . . . . . . . . . 46 - 6.4.8. Getting all available engines . . . . . . . . . . . . 46 - 6.4.9. Getting information about an engine . . . . . . . . . 47 - 6.4.10. Getting sampler channel information . . . . . . . . . 48 - 6.4.11. Current number of active voices . . . . . . . . . . . 51 - 6.4.12. Current number of active disk streams . . . . . . . . 51 - 6.4.13. Current fill state of disk stream buffers . . . . . . 52 - 6.4.14. Setting audio output device . . . . . . . . . . . . . 53 - 6.4.15. Setting audio output type . . . . . . . . . . . . . . 53 - 6.4.16. Setting audio output channel . . . . . . . . . . . . . 54 - 6.4.17. Setting MIDI input device . . . . . . . . . . . . . . 55 - 6.4.18. Setting MIDI input type . . . . . . . . . . . . . . . 56 - 6.4.19. Setting MIDI input port . . . . . . . . . . . . . . . 56 - 6.4.20. Setting MIDI input channel . . . . . . . . . . . . . . 57 - 6.4.21. Setting channel volume . . . . . . . . . . . . . . . . 58 - 6.4.22. Muting a sampler channel . . . . . . . . . . . . . . . 58 - 6.4.23. Soloing a sampler channel . . . . . . . . . . . . . . 59 + parameter . . . . . . . . . . . . . . . . . . . . . . 39 + 6.3.13. Changing settings of MIDI input ports . . . . . . . . 41 + 6.4. Configuring sampler channels . . . . . . . . . . . . . . 42 + 6.4.1. Loading an instrument . . . . . . . . . . . . . . . . 42 + 6.4.2. Loading a sampler engine . . . . . . . . . . . . . . 43 + 6.4.3. Getting all created sampler channel count . . . . . . 44 + 6.4.4. Getting all created sampler channel list . . . . . . 44 + 6.4.5. Adding a new sampler channel . . . . . . . . . . . . 44 + 6.4.6. Removing a sampler channel . . . . . . . . . . . . . 45 + 6.4.7. Getting amount of available engines . . . . . . . . . 46 + 6.4.8. Getting all available engines . . . . . . . . . . . . 46 + 6.4.9. Getting information about an engine . . . . . . . . . 47 + 6.4.10. Getting sampler channel information . . . . . . . . . 48 + 6.4.11. Current number of active voices . . . . . . . . . . . 51 + 6.4.12. Current number of active disk streams . . . . . . . . 51 + 6.4.13. Current fill state of disk stream buffers . . . . . . 52 + 6.4.14. Setting audio output device . . . . . . . . . . . . . 53 + 6.4.15. Setting audio output type . . . . . . . . . . . . . . 53 + 6.4.16. Setting audio output channel . . . . . . . . . . . . 54 + 6.4.17. Setting MIDI input device . . . . . . . . . . . . . . 55 + 6.4.18. Setting MIDI input type . . . . . . . . . . . . . . . 56 + 6.4.19. Setting MIDI input port . . . . . . . . . . . . . . . 56 + 6.4.20. Setting MIDI input channel . . . . . . . . . . . . . 57 + 6.4.21. Setting channel volume . . . . . . . . . . . . . . . 58 + 6.4.22. Muting a sampler channel . . . . . . . . . . . . . . 58 + 6.4.23. Soloing a sampler channel . . . . . . . . . . . . . . 59 6.4.24. Assigning a MIDI instrument map to a sampler - channel . . . . . . . . . . . . . . . . . . . . . . . 60 - 6.4.25. Resetting a sampler channel . . . . . . . . . . . . . 61 - 6.5. Controlling connection . . . . . . . . . . . . . . . . . . 61 - 6.5.1. Register front-end for receiving event messages . . . 61 + channel . . . . . . . . . . . . . . . . . . . . . . . 60 + 6.4.25. Adding an effect send to a sampler channel . . . . . 61 + 6.4.26. Removing an effect send from a sampler channel . . . 62 + 6.4.27. Getting amount of effect sends on a sampler channel . 63 + 6.4.28. Listing all effect sends on a sampler channel . . . . 63 + 6.4.29. Getting effect send information . . . . . . . . . . . 64 + 6.4.30. Altering effect send's audio routing . . . . . . . . 65 + 6.4.31. Altering effect send's MIDI controller . . . . . . . 66 + 6.4.32. Altering effect send's send level . . . . . . . . . . 67 + 6.4.33. Resetting a sampler channel . . . . . . . . . . . . . 68 + 6.5. Controlling connection . . . . . . . . . . . . . . . . . 68 + 6.5.1. Register front-end for receiving event messages . . . 68 6.5.2. Unregister front-end for not receiving event - messages . . . . . . . . . . . . . . . . . . . . . . . 62 - 6.5.3. Enable or disable echo of commands . . . . . . . . . . 63 - 6.5.4. Close client connection . . . . . . . . . . . . . . . 63 - 6.6. Global commands . . . . . . . . . . . . . . . . . . . . . 64 - 6.6.1. Current number of active voices . . . . . . . . . . . 64 - 6.6.2. Maximum amount of active voices . . . . . . . . . . . 64 - 6.6.3. Reset sampler . . . . . . . . . . . . . . . . . . . . 64 - 6.6.4. General sampler informations . . . . . . . . . . . . . 65 - 6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 65 - 6.7.1. Create a new MIDI instrument map . . . . . . . . . . . 66 - 6.7.2. Delete one particular or all MIDI instrument maps . . 67 + messages . . . . . . . . . . . . . . . . . . . . . . 69 + 6.5.3. Enable or disable echo of commands . . . . . . . . . 70 + 6.5.4. Close client connection . . . . . . . . . . . . . . . 70 -Schoenebeck Expires June 23, 2007 [Page 3] - -Internet-Draft LinuxSampler Control Protocol December 2006 - - - 6.7.3. Get amount of existing MIDI instrument maps . . . . . 67 - 6.7.4. Getting all created MIDI instrument maps . . . . . . . 68 - 6.7.5. Getting MIDI instrument map information . . . . . . . 68 - 6.7.6. Renaming a MIDI instrument map . . . . . . . . . . . . 69 - 6.7.7. Create or replace a MIDI instrument map entry . . . . 69 - 6.7.8. Getting ammount of MIDI instrument map entries . . . . 72 +Schoenebeck Expires August 23, 2007 [Page 3] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + + 6.6. Global commands . . . . . . . . . . . . . . . . . . . . . 71 + 6.6.1. Current number of active voices . . . . . . . . . . . 71 + 6.6.2. Maximum amount of active voices . . . . . . . . . . . 71 + 6.6.3. Reset sampler . . . . . . . . . . . . . . . . . . . . 71 + 6.6.4. General sampler informations . . . . . . . . . . . . 72 + 6.6.5. Getting global volume attenuation . . . . . . . . . . 72 + 6.6.6. Setting global volume attenuation . . . . . . . . . . 73 + 6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 73 + 6.7.1. Create a new MIDI instrument map . . . . . . . . . . 74 + 6.7.2. Delete one particular or all MIDI instrument maps . . 75 + 6.7.3. Get amount of existing MIDI instrument maps . . . . . 75 + 6.7.4. Getting all created MIDI instrument maps . . . . . . 76 + 6.7.5. Getting MIDI instrument map information . . . . . . . 76 + 6.7.6. Renaming a MIDI instrument map . . . . . . . . . . . 77 + 6.7.7. Create or replace a MIDI instrument map entry . . . . 77 + 6.7.8. Getting ammount of MIDI instrument map entries . . . 80 6.7.9. Getting indeces of all entries of a MIDI - instrument map . . . . . . . . . . . . . . . . . . . . 73 - 6.7.10. Remove an entry from the MIDI instrument map . . . . . 73 - 6.7.11. Get current settings of MIDI instrument map entry . . 74 - 6.7.12. Clear MIDI instrument map . . . . . . . . . . . . . . 76 - 7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . 77 - 8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 - 8.1. Number of audio output devices changed . . . . . . . . . . 87 - 8.2. Audio output device's settings changed . . . . . . . . . . 87 - 8.3. Number of MIDI input devices changed . . . . . . . . . . . 87 - 8.4. MIDI input device's settings changed . . . . . . . . . . . 88 - 8.5. Number of sampler channels changed . . . . . . . . . . . . 88 - 8.6. Number of active voices changed . . . . . . . . . . . . . 88 - 8.7. Number of active disk streams changed . . . . . . . . . . 89 - 8.8. Disk stream buffer fill state changed . . . . . . . . . . 89 - 8.9. Channel information changed . . . . . . . . . . . . . . . 89 - 8.10. Total number of active voices changed . . . . . . . . . . 90 - 8.11. Number of MIDI instrument maps changed . . . . . . . . . . 90 - 8.12. MIDI instrument map information changed . . . . . . . . . 90 - 8.13. Number of MIDI instruments changed . . . . . . . . . . . . 91 - 8.14. MIDI instrument information changed . . . . . . . . . . . 91 - 8.15. Miscellaneous and debugging events . . . . . . . . . . . . 92 - 9. Security Considerations . . . . . . . . . . . . . . . . . . . 93 - 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 94 - 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 95 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 96 - Intellectual Property and Copyright Statements . . . . . . . . . . 97 + instrument map . . . . . . . . . . . . . . . . . . . 81 + 6.7.10. Remove an entry from the MIDI instrument map . . . . 82 + 6.7.11. Get current settings of MIDI instrument map entry . . 82 + 6.7.12. Clear MIDI instrument map . . . . . . . . . . . . . . 84 + 7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . 85 + 8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 + 8.1. Number of audio output devices changed . . . . . . . . . 96 + 8.2. Audio output device's settings changed . . . . . . . . . 96 + 8.3. Number of MIDI input devices changed . . . . . . . . . . 96 + 8.4. MIDI input device's settings changed . . . . . . . . . . 97 + 8.5. Number of sampler channels changed . . . . . . . . . . . 97 + 8.6. Number of active voices changed . . . . . . . . . . . . . 97 + 8.7. Number of active disk streams changed . . . . . . . . . . 98 + 8.8. Disk stream buffer fill state changed . . . . . . . . . . 98 + 8.9. Channel information changed . . . . . . . . . . . . . . . 98 + 8.10. Total number of active voices changed . . . . . . . . . . 99 + 8.11. Number of MIDI instrument maps changed . . . . . . . . . 99 + 8.12. MIDI instrument map information changed . . . . . . . . . 99 + 8.13. Number of MIDI instruments changed . . . . . . . . . . . 100 + 8.14. MIDI instrument information changed . . . . . . . . . . . 100 + 8.15. Miscellaneous and debugging events . . . . . . . . . . . 101 + 9. Security Considerations . . . . . . . . . . . . . . . . . . . 102 + 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 103 + 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 104 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 105 + Intellectual Property and Copyright Statements . . . . . . . . . 106 @@ -210,19 +220,9 @@ - - - - - - - - - - -Schoenebeck Expires June 23, 2007 [Page 4] +Schoenebeck Expires August 23, 2007 [Page 4] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 1. Requirements notation @@ -276,9 +276,9 @@ -Schoenebeck Expires June 23, 2007 [Page 5] +Schoenebeck Expires August 23, 2007 [Page 5] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 2. Versioning of this specification @@ -332,9 +332,9 @@ -Schoenebeck Expires June 23, 2007 [Page 6] +Schoenebeck Expires August 23, 2007 [Page 6] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 3. Introduction @@ -388,9 +388,9 @@ -Schoenebeck Expires June 23, 2007 [Page 7] +Schoenebeck Expires August 23, 2007 [Page 7] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 4. Focus of this protocol @@ -444,9 +444,9 @@ -Schoenebeck Expires June 23, 2007 [Page 8] +Schoenebeck Expires August 23, 2007 [Page 8] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 5. Communication Overview @@ -500,9 +500,9 @@ -Schoenebeck Expires June 23, 2007 [Page 9] +Schoenebeck Expires August 23, 2007 [Page 9] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 5.1.1. Result format @@ -556,9 +556,9 @@ -Schoenebeck Expires June 23, 2007 [Page 10] +Schoenebeck Expires August 23, 2007 [Page 10] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 set has the following format: @@ -612,9 +612,9 @@ -Schoenebeck Expires June 23, 2007 [Page 11] +Schoenebeck Expires August 23, 2007 [Page 11] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 Each line of the result set MUST end with . @@ -668,9 +668,9 @@ -Schoenebeck Expires June 23, 2007 [Page 12] +Schoenebeck Expires August 23, 2007 [Page 12] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 inserted in the middle of the event message as well as any other @@ -724,9 +724,9 @@ -Schoenebeck Expires June 23, 2007 [Page 13] +Schoenebeck Expires August 23, 2007 [Page 13] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 6. Description for control commands @@ -780,9 +780,9 @@ -Schoenebeck Expires June 23, 2007 [Page 14] +Schoenebeck Expires August 23, 2007 [Page 14] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 6.2.1. Getting amount of available audio output drivers @@ -836,9 +836,9 @@ -Schoenebeck Expires June 23, 2007 [Page 15] +Schoenebeck Expires August 23, 2007 [Page 15] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 LinuxSampler will answer by sending a separated list. Each @@ -892,9 +892,9 @@ -Schoenebeck Expires June 23, 2007 [Page 16] +Schoenebeck Expires August 23, 2007 [Page 16] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO" @@ -948,9 +948,9 @@ -Schoenebeck Expires June 23, 2007 [Page 17] +Schoenebeck Expires August 23, 2007 [Page 17] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 MULTIPLICITY - @@ -1004,9 +1004,9 @@ -Schoenebeck Expires June 23, 2007 [Page 18] +Schoenebeck Expires August 23, 2007 [Page 18] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 returned, dependent to driver parameter) @@ -1060,9 +1060,9 @@ -Schoenebeck Expires June 23, 2007 [Page 19] +Schoenebeck Expires August 23, 2007 [Page 19] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "TYPE: INT" @@ -1116,9 +1116,9 @@ -Schoenebeck Expires June 23, 2007 [Page 20] +Schoenebeck Expires August 23, 2007 [Page 20] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 providing an appropriate warning code and warning message @@ -1172,9 +1172,9 @@ -Schoenebeck Expires June 23, 2007 [Page 21] +Schoenebeck Expires August 23, 2007 [Page 21] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 C: "DESTROY AUDIO_OUTPUT_DEVICE 0" @@ -1228,9 +1228,9 @@ -Schoenebeck Expires June 23, 2007 [Page 22] +Schoenebeck Expires August 23, 2007 [Page 22] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 Possible Answers: @@ -1284,9 +1284,9 @@ -Schoenebeck Expires June 23, 2007 [Page 23] +Schoenebeck Expires August 23, 2007 [Page 23] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "FRAGMENTS: 2" @@ -1340,9 +1340,9 @@ -Schoenebeck Expires June 23, 2007 [Page 24] +Schoenebeck Expires August 23, 2007 [Page 24] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 6.2.11. Getting information about an audio channel @@ -1396,9 +1396,9 @@ -Schoenebeck Expires June 23, 2007 [Page 25] +Schoenebeck Expires August 23, 2007 [Page 25] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 Examples: @@ -1452,9 +1452,9 @@ -Schoenebeck Expires June 23, 2007 [Page 26] +Schoenebeck Expires August 23, 2007 [Page 26] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 channel number and a specific channel parameter name for @@ -1508,9 +1508,9 @@ -Schoenebeck Expires June 23, 2007 [Page 27] +Schoenebeck Expires August 23, 2007 [Page 27] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 RANGE_MAX - @@ -1564,9 +1564,9 @@ -Schoenebeck Expires June 23, 2007 [Page 28] +Schoenebeck Expires August 23, 2007 [Page 28] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "OK" - @@ -1620,9 +1620,9 @@ -Schoenebeck Expires June 23, 2007 [Page 29] +Schoenebeck Expires August 23, 2007 [Page 29] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 Note: examples in this chapter showing particular parameters of @@ -1676,9 +1676,9 @@ -Schoenebeck Expires June 23, 2007 [Page 30] +Schoenebeck Expires August 23, 2007 [Page 30] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 6.3.3. Getting information about a specific MIDI input driver @@ -1732,9 +1732,9 @@ -Schoenebeck Expires June 23, 2007 [Page 31] +Schoenebeck Expires August 23, 2007 [Page 31] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 6.3.4. Getting information about specific MIDI input driver parameter @@ -1788,9 +1788,9 @@ -Schoenebeck Expires June 23, 2007 [Page 32] +Schoenebeck Expires August 23, 2007 [Page 32] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 FIX - @@ -1844,9 +1844,9 @@ -Schoenebeck Expires June 23, 2007 [Page 33] +Schoenebeck Expires August 23, 2007 [Page 33] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 may also appear without (optionally returned, dependent to @@ -1900,9 +1900,9 @@ -Schoenebeck Expires June 23, 2007 [Page 34] +Schoenebeck Expires August 23, 2007 [Page 34] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "OK[]" - @@ -1956,9 +1956,9 @@ -Schoenebeck Expires June 23, 2007 [Page 35] +Schoenebeck Expires August 23, 2007 [Page 35] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 in case it failed, providing an appropriate error code and @@ -2012,9 +2012,9 @@ -Schoenebeck Expires June 23, 2007 [Page 36] +Schoenebeck Expires August 23, 2007 [Page 36] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 6.3.9. Getting current settings of a MIDI input device @@ -2068,9 +2068,9 @@ -Schoenebeck Expires June 23, 2007 [Page 37] +Schoenebeck Expires August 23, 2007 [Page 37] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "ACTIVE: true" @@ -2124,9 +2124,9 @@ -Schoenebeck Expires June 23, 2007 [Page 38] +Schoenebeck Expires August 23, 2007 [Page 38] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 MIDI_INPUT_DEVICES" (Section 6.3.8) command and the MIDI @@ -2180,9 +2180,9 @@ -Schoenebeck Expires June 23, 2007 [Page 39] +Schoenebeck Expires August 23, 2007 [Page 39] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 character string to that info category. There is information @@ -2236,9 +2236,9 @@ -Schoenebeck Expires June 23, 2007 [Page 40] +Schoenebeck Expires August 23, 2007 [Page 40] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 returned, dependent to device and port parameter) @@ -2292,9 +2292,9 @@ -Schoenebeck Expires June 23, 2007 [Page 41] +Schoenebeck Expires August 23, 2007 [Page 41] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 in case it failed, providing an appropriate error code and @@ -2348,9 +2348,9 @@ -Schoenebeck Expires June 23, 2007 [Page 42] +Schoenebeck Expires August 23, 2007 [Page 42] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 or more patch parameters provided by the loaded instrument @@ -2404,9 +2404,9 @@ -Schoenebeck Expires June 23, 2007 [Page 43] +Schoenebeck Expires August 23, 2007 [Page 43] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 Example: @@ -2460,9 +2460,9 @@ -Schoenebeck Expires June 23, 2007 [Page 44] +Schoenebeck Expires August 23, 2007 [Page 44] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 ADD CHANNEL @@ -2516,9 +2516,9 @@ -Schoenebeck Expires June 23, 2007 [Page 45] +Schoenebeck Expires August 23, 2007 [Page 45] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "OK" - @@ -2572,9 +2572,9 @@ -Schoenebeck Expires June 23, 2007 [Page 46] +Schoenebeck Expires August 23, 2007 [Page 46] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 LinuxSampler will answer by sending a comma separated list of the @@ -2628,9 +2628,9 @@ -Schoenebeck Expires June 23, 2007 [Page 47] +Schoenebeck Expires August 23, 2007 [Page 47] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "VERSION: testing-1.0" @@ -2684,9 +2684,9 @@ -Schoenebeck Expires June 23, 2007 [Page 48] +Schoenebeck Expires August 23, 2007 [Page 48] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 output channel 0 is routed to channel 0 of the audio output @@ -2740,9 +2740,9 @@ -Schoenebeck Expires June 23, 2007 [Page 49] +Schoenebeck Expires August 23, 2007 [Page 49] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 MUTE - @@ -2796,9 +2796,9 @@ -Schoenebeck Expires June 23, 2007 [Page 50] +Schoenebeck Expires August 23, 2007 [Page 50] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "MIDI_INPUT_CHANNEL: 5" @@ -2852,9 +2852,9 @@ -Schoenebeck Expires June 23, 2007 [Page 51] +Schoenebeck Expires August 23, 2007 [Page 51] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 return "NA" for not available. @@ -2908,9 +2908,9 @@ -Schoenebeck Expires June 23, 2007 [Page 52] +Schoenebeck Expires August 23, 2007 [Page 52] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 S: "" @@ -2964,9 +2964,9 @@ -Schoenebeck Expires June 23, 2007 [Page 53] +Schoenebeck Expires August 23, 2007 [Page 53] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 Where is currently either "ALSA" or "JACK" and @@ -3020,9 +3020,9 @@ -Schoenebeck Expires June 23, 2007 [Page 54] +Schoenebeck Expires August 23, 2007 [Page 54] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 if audio output channel was set, but there are noteworthy @@ -3076,9 +3076,9 @@ -Schoenebeck Expires June 23, 2007 [Page 55] +Schoenebeck Expires August 23, 2007 [Page 55] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 6.4.18. Setting MIDI input type @@ -3132,9 +3132,9 @@ -Schoenebeck Expires June 23, 2007 [Page 56] +Schoenebeck Expires August 23, 2007 [Page 56] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 on success @@ -3188,9 +3188,9 @@ -Schoenebeck Expires June 23, 2007 [Page 57] +Schoenebeck Expires August 23, 2007 [Page 57] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 @@ -3244,9 +3244,9 @@ -Schoenebeck Expires June 23, 2007 [Page 58] +Schoenebeck Expires August 23, 2007 [Page 58] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "OK" - @@ -3300,9 +3300,9 @@ -Schoenebeck Expires June 23, 2007 [Page 59] +Schoenebeck Expires August 23, 2007 [Page 59] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 Examples: @@ -3356,16 +3356,408 @@ -Schoenebeck Expires June 23, 2007 [Page 60] +Schoenebeck Expires August 23, 2007 [Page 60] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + + Examples: + + + +6.4.25. Adding an effect send to a sampler channel + + The front-end can create an additional effect send on a specific + sampler channel by sending the following command: + + CREATE FX_SEND [] + + Where is the respective sampler channel number as + returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" + (Section 6.4.4) command, that is the sampler channel on which the + effect send should be created on, is a number between + 0..127 defining the MIDI controller which can alter the effect send + level and is an optional argument defining a name for the + effect send entity. The name does not have to be unique. + + By default, that is as initial routing, the effect send's audio + channels are automatically routed to the last audio channels of the + sampler channel's audio output device, that way you can i.e. first + increase the amount of audio channels on the audio output device for + having dedicated effect send output channels and when "CREATE + FX_SEND" is called, those channels will automatically be picked. You + can alter the destination channels however with "SET FX_SEND + AUDIO_OUTPUT_CHANNEL" (Section 6.4.30). + + Note: Create effect sends on a sampler channel only when needed, + because having effect sends on a sampler channel will decrease + runtime performance, because for implementing channel effect sends, + separate (sampler channel local) audio buffers are needed to render + and mix the voices and route the audio signal afterwards to the + master outputs and effect send outputs (along with their respective + effect send levels). A sampler channel without effect sends however + can mix its voices directly into the audio output devices's audio + buffers and is thus faster. + + Possible Answers: + + "OK[]" - + + in case a new effect send could be added to the sampler + channel, where reflects the unique ID of the newly + created effect send entity + + + + + + +Schoenebeck Expires August 23, 2007 [Page 61] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 + "ERR::" - + + when a new effect send could not be added, i.e. due to invalid + parameters + Examples: + C: "CREATE FX_SEND 0 91 'Reverb Send'" + + S: "OK[0]" + + C: "CREATE FX_SEND 0 93" + + S: "OK[1]" + +6.4.26. Removing an effect send from a sampler channel + + The front-end can remove an existing effect send on a specific + sampler channel by sending the following command: + + DESTROY FX_SEND + + Where is the respective sampler channel number as + returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" + (Section 6.4.4) command, that is the sampler channel from which the + effect send should be removed from and is the respective + effect send number as returned by the "CREATE FX_SEND" + (Section 6.4.25) or "LIST FX_SENDS" (Section 6.4.28) command. + + Possible Answers: + + "OK" - + + on success + + "ERR::" - + + in case it failed, providing an appropriate error code and + error message + + Example: + + C: "DESTROY FX_SEND 0 0" + + S: "OK" + + + + + + +Schoenebeck Expires August 23, 2007 [Page 62] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + +6.4.27. Getting amount of effect sends on a sampler channel + + The front-end can ask for the amount of effect sends on a specific + sampler channel by sending the following command: + + GET FX_SENDS + + Where is the respective sampler channel number as + returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" + (Section 6.4.4) command. + + Possible Answers: + + The sampler will answer by returning the number of effect sends on + the given sampler channel. + + Example: + + C: "GET FX_SENDS 0" + + S: "2" + +6.4.28. Listing all effect sends on a sampler channel + + The front-end can ask for a list of effect sends on a specific + sampler channel by sending the following command: + + LIST FX_SENDS + + Where is the respective sampler channel number as + returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" + (Section 6.4.4) command. + + Possible Answers: + + The sampler will answer by returning a comma separated list with + all effect sends' numerical IDs on the given sampler channel. + + Examples: + + C: "LIST FX_SENDS 0" + + S: "0,1" + + C: "LIST FX_SENDS 1" + + S: "" + + + + +Schoenebeck Expires August 23, 2007 [Page 63] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + +6.4.29. Getting effect send information + + The front-end can ask for the current settings of an effect send + entity by sending the following command: + + GET FX_SEND INFO + + Where is the sampler channel number as returned by + the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4) + command and reflects the numerical ID of the effect send + entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST + FX_SENDS" (Section 6.4.28) command. + + Possible Answers: + + The sampler will answer by sending a separated list. Each + answer line begins with the settings category name followed by a + colon and then a space character and finally the info + character string to that setting category. At the moment the + following categories are defined: + + + + NAME - + + name of the effect send entity + + MIDI_CONTROLLER - + + a value between 0 and 127 reflecting the MIDI controller + which is able to modify the effect send's send level + + LEVEL - + + optionally dotted number reflecting the effect send's + current send level (where a value < 1.0 means attenuation + and a value > 1.0 means amplification) + + AUDIO_OUTPUT_ROUTING - + + comma separated list which reflects to which audio channel + of the selected audio output device each effect send output + channel is routed to, e.g. "0,3" would mean the effect + send's output channel 0 is routed to channel 0 of the audio + output device and the effect send's output channel 1 is + routed to the channel 3 of the audio output device (see "SET + FX_SEND AUDIO_OUTPUT_CHANNEL" (Section 6.4.30) for details) + + + + +Schoenebeck Expires August 23, 2007 [Page 64] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + + The mentioned fields above don't have to be in particular order. + + Example: + + C: "GET FX_SEND INFO 0 0" + + S: "NAME: Reverb Send" + + "MIDI_CONTROLLER: 91" + + "LEVEL: 0.3" + + "AUDIO_OUTPUT_ROUTING: 2,3" + + "." + +6.4.30. Altering effect send's audio routing + + The front-end can alter the destination of an effect send's audio + channel on a specific sampler channel by sending the following + command: + + SET FX_SEND AUDIO_OUTPUT_CHANNEL + + + Where is the sampler channel number as returned by the + "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4) + command, reflects the numerical ID of the effect send + entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST + FX_SENDS" (Section 6.4.28) command, is the numerical ID + of the effect send's audio channel which should be rerouted and + is the numerical ID of the audio channel of the selected + audio output device where should be routed to. + + Note that effect sends can only route audio to the same audio output + device as assigned to the effect send's sampler channel. Also note + that an effect send entity does always have exactly as much audio + channels as its sampler channel. So if the sampler channel is + stereo, the effect send does have two audio channels as well. Also + keep in mind that the amount of audio channels on a sampler channel + might be dependant not only to the deployed sampler engine on the + sampler channel, but also dependant to the instrument currently + loaded. However you can (effectively) turn an i.e. stereo effect + send into a mono one by simply altering its audio routing + appropriately. + + Possible Answers: + + + + +Schoenebeck Expires August 23, 2007 [Page 65] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + + "OK" - + + on success + + "WRN::" - + + if audio output channel was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message + + "ERR::" - + + in case it failed, providing an appropriate error code and + error message + + Example: + + C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2" + + S: "OK" + +6.4.31. Altering effect send's MIDI controller + + The front-end can alter the MIDI controller of an effect send entity + by sending the following command: + + SET FX_SEND MIDI_CONTROLLER + + Where is the sampler channel number as returned by the + "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4) + command, reflects the numerical ID of the effect send + entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST + FX_SENDS" (Section 6.4.28) command and reflects the MIDI + controller which shall be able to modify the effect send's send + level. + + Possible Answers: + + "OK" - + + on success + + "WRN::" - + + if MIDI controller was set, but there are noteworthy issue(s) + related, providing an appropriate warning code and warning + message + + + +Schoenebeck Expires August 23, 2007 [Page 66] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + + "ERR::" - + + in case it failed, providing an appropriate error code and + error message + + Example: + + C: "SET FX_SEND MIDI_CONTROLLER 0 0 91" + + S: "OK" + +6.4.32. Altering effect send's send level + + The front-end can alter the current send level of an effect send + entity by sending the following command: + + SET FX_SEND LEVEL + + Where is the sampler channel number as returned by the + "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4) + command, reflects the numerical ID of the effect send + entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST + FX_SENDS" (Section 6.4.28) command and is an optionally + dotted positive number (a value smaller than 1.0 means attenuation, + whereas a value greater than 1.0 means amplification) reflecting the + new send level. + + Possible Answers: + + "OK" - + + on success + + "WRN::" - + + if new send level was set, but there are noteworthy issue(s) + related, providing an appropriate warning code and warning + message + + "ERR::" - + + in case it failed, providing an appropriate error code and + error message + + Example: + + + + + + +Schoenebeck Expires August 23, 2007 [Page 67] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + + C: "SET FX_SEND LEVEL 0 0 0.15" + S: "OK" -6.4.25. Resetting a sampler channel +6.4.33. Resetting a sampler channel The front-end can reset a particular sampler channel by sending the following command: @@ -3412,9 +3804,9 @@ -Schoenebeck Expires June 23, 2007 [Page 61] +Schoenebeck Expires August 23, 2007 [Page 68] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 SUBSCRIBE @@ -3468,9 +3860,9 @@ -Schoenebeck Expires June 23, 2007 [Page 62] +Schoenebeck Expires August 23, 2007 [Page 69] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "ERR::" - @@ -3524,9 +3916,9 @@ -Schoenebeck Expires June 23, 2007 [Page 63] +Schoenebeck Expires August 23, 2007 [Page 70] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 6.6. Global commands @@ -3580,9 +3972,9 @@ -Schoenebeck Expires June 23, 2007 [Page 64] +Schoenebeck Expires August 23, 2007 [Page 71] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 6.6.4. General sampler informations @@ -3618,6 +4010,60 @@ The mentioned fields above don't have to be in particular order. Other fields might be added in future. +6.6.5. Getting global volume attenuation + + The client can ask for the current global sampler-wide volume + attenuation by sending the following command: + + GET VOLUME + + Possible Answers: + + The sampler will always answer by returning the optional dotted + floating point coefficient, reflecting the current global volume + attenuation. + + Note: it is up to the respective sampler engine whether to obey that + global volume parameter or not, but in general all engines SHOULD use + + + +Schoenebeck Expires August 23, 2007 [Page 72] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + + this parameter. + +6.6.6. Setting global volume attenuation + + The client can alter the current global sampler-wide volume + attenuation by sending the following command: + + SET VOLUME + + Where should be replaced by the optional dotted floating + point value, reflecting the new global volume parameter. This value + might usually be in the range between 0.0 and 1.0, that is for + attenuating the overall volume. + + Possible Answers: + + "OK" - + + on success + + "WRN::" - + + if the global volume was set, but there are noteworthy issue(s) + related, providing an appropriate warning code and warning + message + + "ERR::" - + + in case it failed, providing an appropriate error code and + error message + 6.7. MIDI Instrument Mapping The MIDI protocol provides a way to switch between instruments by @@ -3633,16 +4079,16 @@ By default, that is when the sampler is launched, there is no map, thus the sampler will simply ignore all program change messages. The front-end has to explicitly create at least one map, add entries to + the map and tell the respective sampler channel(s) which MIDI + instrument map to use, so the sampler knows how to react on a given -Schoenebeck Expires June 23, 2007 [Page 65] +Schoenebeck Expires August 23, 2007 [Page 73] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 - the map and tell the respective sampler channel(s) which MIDI - instrument map to use, so the sampler knows how to react on a given program change message on the respective sampler channel, that is by switching to the respectively defined engine type and loading the respective instrument. See command "SET CHANNEL MIDI_INSTRUMENT_MAP" @@ -3688,17 +4134,17 @@ S: "OK[1]" + C: "ADD MIDI_INSTRUMENT_MAP" + -Schoenebeck Expires June 23, 2007 [Page 66] +Schoenebeck Expires August 23, 2007 [Page 74] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 - C: "ADD MIDI_INSTRUMENT_MAP" - S: "OK[5]" 6.7.2. Delete one particular or all MIDI instrument maps @@ -3748,9 +4194,11 @@ -Schoenebeck Expires June 23, 2007 [Page 67] + + +Schoenebeck Expires August 23, 2007 [Page 75] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 The sampler will answer by returning the current number of MIDI @@ -3804,9 +4252,9 @@ -Schoenebeck Expires June 23, 2007 [Page 68] +Schoenebeck Expires August 23, 2007 [Page 76] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 @@ -3860,14 +4308,14 @@ -Schoenebeck Expires June 23, 2007 [Page 69] +Schoenebeck Expires August 23, 2007 [Page 77] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 - MAP MIDI_INSTRUMENT - [] - [] + MAP MIDI_INSTRUMENT [NON_MODAL] + + [] [] Where is the numeric ID of the map to alter, is an integer value between 0..16383 reflecting the MIDI bank select index, @@ -3905,20 +4353,20 @@ "PERSISTENT" - - The instrument will immediately be loaded into memory in the - background when this mapping command is sent and the instrument - is kept all the time. Instruments with this mode are only - freed when the sampler is reset or all mapping entries with - this mode (and respective instrument) are explicitly changed to - "ON_DEMAND" and no sampler channel is using the instrument - anymore. + The instrument will immediately be loaded into memory when this + mapping command is sent and the instrument is kept all the + time. Instruments with this mode are only freed when the + sampler is reset or all mapping entries with this mode (and + respective instrument) are explicitly changed to "ON_DEMAND" + and no sampler channel is using the instrument anymore. + -Schoenebeck Expires June 23, 2007 [Page 70] +Schoenebeck Expires August 23, 2007 [Page 78] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 not supplied - @@ -3950,15 +4398,33 @@ displaying an appropriate name for mapped instruments (using "GET MIDI_INSTRUMENT INFO" (Section 6.7.11)). - The "MAP MIDI_INSTRUMENT" command will immediately return, thus it - will not block when an instrument is to be loaded due to a - "PERSISTENT" type entry as instruments are loaded in the background. - As a consequence this command may not necessarily return an error - i.e. when the given instrument file does not exist or may turn out to - be corrupt. + By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is + completely established in the sampler. The OPTIONAL "NON_MODAL" + argument however causes the respective "MAP MIDI_INSTRUMENT" command + to return immediately, that is to let the sampler establish the + mapping in the background. So this argument might be especially + useful for mappings with a "PERSISTENT" type, because these have to + load the respective instruments immediately and might thus block for + a very long time. It is recommended however to use the OPTIONAL + "NON_MODAL" argument only if really necessary, because it has the + following drawbacks: as "NON_MODAL" instructions return immediately, + they may not necessarily return an error i.e. when the given + instrument file turns out to be corrupt, beside that subsequent + commands in a LSCP instruction sequence might fail, because mandatory + mappings are not yet completed. Possible Answers: + + + + + +Schoenebeck Expires August 23, 2007 [Page 79] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + "OK" - usually @@ -3970,13 +4436,6 @@ Examples: - - -Schoenebeck Expires June 23, 2007 [Page 71] - -Internet-Draft LinuxSampler Control Protocol December 2006 - - C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT" @@ -3997,8 +4456,8 @@ S: "OK" - C: "MAP MIDI_INSTRUMENT 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 - PERSISTENT 'Foo Drumkit'" + C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/ + foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'" S: "OK" @@ -4012,6 +4471,16 @@ The front-end can query the amount of currently existing entries in all MIDI instrument maps by sending the following command: + + + + + +Schoenebeck Expires August 23, 2007 [Page 80] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + GET MIDI_INSTRUMENTS ALL Possible Answers: @@ -4025,14 +4494,6 @@ S: "234" - - - -Schoenebeck Expires June 23, 2007 [Page 72] - -Internet-Draft LinuxSampler Control Protocol December 2006 - - C: "GET MIDI_INSTRUMENTS ALL" S: "954" @@ -4067,6 +4528,15 @@ S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}" + + + + +Schoenebeck Expires August 23, 2007 [Page 81] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + 6.7.10. Remove an entry from the MIDI instrument map The front-end can delete an entry from a MIDI instrument map by @@ -4081,14 +4551,6 @@ Possible Answers: - - - -Schoenebeck Expires June 23, 2007 [Page 73] - -Internet-Draft LinuxSampler Control Protocol December 2006 - - "OK" - usually @@ -4124,6 +4586,13 @@ character string to that info category. At the moment the following categories are defined: + + +Schoenebeck Expires August 23, 2007 [Page 82] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + "NAME" - Name for this MIDI instrument map entry (if defined). This @@ -4136,15 +4605,6 @@ Name of the engine to be deployed for this instrument. - - - - -Schoenebeck Expires June 23, 2007 [Page 74] - -Internet-Draft LinuxSampler Control Protocol December 2006 - - "INSTRUMENT_FILE" - File name of the instrument. @@ -4180,26 +4640,26 @@ "ENGINE_NAME: GigEngine" - "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig" - "INSTRUMENT_NR: 0" - "INSTRUMENT_NAME: Joe's Drumkit" - "LOAD_MODE: PERSISTENT" - "VOLUME: 1.0" +Schoenebeck Expires August 23, 2007 [Page 83] + +Internet-Draft LinuxSampler Control Protocol February 2007 - "." + "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig" + "INSTRUMENT_NR: 0" + "INSTRUMENT_NAME: Joe's Drumkit" + "LOAD_MODE: PERSISTENT" -Schoenebeck Expires June 23, 2007 [Page 75] - -Internet-Draft LinuxSampler Control Protocol December 2006 + "VOLUME: 1.0" + "." 6.7.12. Clear MIDI instrument map @@ -4240,21 +4700,9 @@ - - - - - - - - - - - - -Schoenebeck Expires June 23, 2007 [Page 76] +Schoenebeck Expires August 23, 2007 [Page 84] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 7. Command Syntax @@ -4308,9 +4756,9 @@ -Schoenebeck Expires June 23, 2007 [Page 77] +Schoenebeck Expires August 23, 2007 [Page 85] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 / LIST SP list_instruction @@ -4364,9 +4812,9 @@ -Schoenebeck Expires June 23, 2007 [Page 78] +Schoenebeck Expires August 23, 2007 [Page 86] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 / CHANNEL_INFO @@ -4420,24 +4868,24 @@ -Schoenebeck Expires June 23, 2007 [Page 79] +Schoenebeck Expires August 23, 2007 [Page 87] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 - MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP + MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value - / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP - engine_name SP filename SP instrument_index SP volume_value SP + / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog + SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode - / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP - engine_name SP filename SP instrument_index SP volume_value SP + / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog + SP engine_name SP filename SP instrument_index SP volume_value SP entry_name - / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP - engine_name SP filename SP instrument_index SP volume_value SP + / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog + SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name unmap_instruction = @@ -4476,9 +4924,9 @@ -Schoenebeck Expires June 23, 2007 [Page 80] +Schoenebeck Expires August 23, 2007 [Page 88] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 / AUDIO_OUTPUT_DEVICES @@ -4526,16 +4974,22 @@ / MIDI_INSTRUMENT_MAP SP INFO SP midi_map - set_instruction = + / FX_SENDS SP sampler_channel -Schoenebeck Expires June 23, 2007 [Page 81] +Schoenebeck Expires August 23, 2007 [Page 89] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 + + / FX_SEND SP INFO SP sampler_channel SP fx_send_id + + / VOLUME + + set_instruction = AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list @@ -4553,8 +5007,19 @@ / MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name + / FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id + SP audio_channel_index SP audio_channel_index + + / FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP + midi_ctrl + + / FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP + volume_value + / ECHO SP boolean + / VOLUME SP volume_value + create_instruction = AUDIO_OUTPUT_DEVICE SP string SP key_val_list @@ -4565,6 +5030,19 @@ / MIDI_INPUT_DEVICE SP string + / FX_SEND SP sampler_channel SP midi_ctrl + + + + + +Schoenebeck Expires August 23, 2007 [Page 90] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + + / FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name + reset_instruction = CHANNEL SP sampler_channel @@ -4581,18 +5059,12 @@ / MIDI_INPUT_DEVICE SP number + / FX_SEND SP sampler_channel SP fx_send_id + load_instruction = INSTRUMENT SP load_instr_args - - - -Schoenebeck Expires June 23, 2007 [Page 82] - -Internet-Draft LinuxSampler Control Protocol December 2006 - - / ENGINE SP load_engine_args set_chan_instruction = @@ -4616,6 +5088,15 @@ / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name + + + + +Schoenebeck Expires August 23, 2007 [Page 91] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + / VOLUME SP sampler_channel SP volume_value / MUTE SP sampler_channel SP boolean @@ -4628,6 +5109,12 @@ / MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT + modal_arg = + + /* epsilon (empty argument) */ + + / NON_MODAL SP + key_val_list = string '=' param_val_list @@ -4642,13 +5129,6 @@ list_instruction = - - -Schoenebeck Expires June 23, 2007 [Page 83] - -Internet-Draft LinuxSampler Control Protocol December 2006 - - AUDIO_OUTPUT_DEVICES / MIDI_INPUT_DEVICES @@ -4665,8 +5145,18 @@ / MIDI_INSTRUMENTS SP ALL + + + +Schoenebeck Expires August 23, 2007 [Page 92] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + / MIDI_INSTRUMENT_MAPS + / FX_SENDS SP sampler_channel + load_instr_args = filename SP instrument_index SP sampler_channel @@ -4697,14 +5187,6 @@ string - - - -Schoenebeck Expires June 23, 2007 [Page 84] - -Internet-Draft LinuxSampler Control Protocol December 2006 - - midi_input_port_index = number @@ -4719,6 +5201,14 @@ string + + + +Schoenebeck Expires August 23, 2007 [Page 93] + +Internet-Draft LinuxSampler Control Protocol February 2007 + + midi_map = number @@ -4731,6 +5221,10 @@ number + midi_ctrl = + + number + volume_value = dotnum @@ -4745,6 +5239,10 @@ number + fx_send_id = + + number + engine_name = string @@ -4753,19 +5251,23 @@ stringval + map_name = + stringval + entry_name = -Schoenebeck Expires June 23, 2007 [Page 85] - -Internet-Draft LinuxSampler Control Protocol December 2006 - map_name = + +Schoenebeck Expires August 23, 2007 [Page 94] + +Internet-Draft LinuxSampler Control Protocol February 2007 + stringval - entry_name = + fx_send_name = stringval @@ -4812,9 +5314,11 @@ -Schoenebeck Expires June 23, 2007 [Page 86] + + +Schoenebeck Expires August 23, 2007 [Page 95] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 8. Events @@ -4868,9 +5372,9 @@ -Schoenebeck Expires June 23, 2007 [Page 87] +Schoenebeck Expires August 23, 2007 [Page 96] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "NOTIFY:MIDI_INPUT_DEVICE_COUNT:" @@ -4924,9 +5428,9 @@ -Schoenebeck Expires June 23, 2007 [Page 88] +Schoenebeck Expires August 23, 2007 [Page 97] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "NOTIFY:VOICE_COUNT: @@ -4980,9 +5484,9 @@ -Schoenebeck Expires June 23, 2007 [Page 89] +Schoenebeck Expires August 23, 2007 [Page 98] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "NOTIFY:CHANNEL_INFO:" @@ -5036,9 +5540,9 @@ -Schoenebeck Expires June 23, 2007 [Page 90] +Schoenebeck Expires August 23, 2007 [Page 99] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 "NOTIFY:MIDI_INSTRUMENT_MAP_INFO:" @@ -5092,9 +5596,9 @@ -Schoenebeck Expires June 23, 2007 [Page 91] +Schoenebeck Expires August 23, 2007 [Page 100] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 8.15. Miscellaneous and debugging events @@ -5148,9 +5652,9 @@ -Schoenebeck Expires June 23, 2007 [Page 92] +Schoenebeck Expires August 23, 2007 [Page 101] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 9. Security Considerations @@ -5204,9 +5708,9 @@ -Schoenebeck Expires June 23, 2007 [Page 93] +Schoenebeck Expires August 23, 2007 [Page 102] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 10. Acknowledgments @@ -5260,9 +5764,9 @@ -Schoenebeck Expires June 23, 2007 [Page 94] +Schoenebeck Expires August 23, 2007 [Page 103] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 11. References @@ -5316,9 +5820,9 @@ -Schoenebeck Expires June 23, 2007 [Page 95] +Schoenebeck Expires August 23, 2007 [Page 104] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 Author's Address @@ -5372,14 +5876,14 @@ -Schoenebeck Expires June 23, 2007 [Page 96] +Schoenebeck Expires August 23, 2007 [Page 105] -Internet-Draft LinuxSampler Control Protocol December 2006 +Internet-Draft LinuxSampler Control Protocol February 2007 Full Copyright Statement - Copyright (C) The Internet Society (2006). + Copyright (C) The Internet Society (2007). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors @@ -5428,5 +5932,5 @@ -Schoenebeck Expires June 23, 2007 [Page 97] +Schoenebeck Expires August 23, 2007 [Page 106]