--- web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt 2019/03/11 15:42:54 3502 +++ web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt 2019/03/11 15:46:15 3503 @@ -1,10 +1,11 @@ -LinuxSampler Developers C. Schoenebeck + +LinuxSampler Developers C. Schoenebeck, Ed. Internet-Draft LinuxSampler.org -Intended status: Standards Track July 15, 2015 -Expires: January 16, 2016 +Intended status: Informational March 11, 2019 +Expires: September 12, 2019 LinuxSampler Control Protocol @@ -18,12 +19,10 @@ like console application essentially playing back audio samples and manipulating the samples in real time to certain extent. -Status of this Memo +Status of This Memo - By submitting this Internet-Draft, each author represents that any - applicable patent or other IPR claims of which he or she is aware - have been or will be disclosed, and any of which he or she becomes - aware will be disclosed, in accordance with Section 6 of BCP 79. + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute @@ -35,307 +34,274 @@ time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on January 16, 2016. - - - - - - - + This Internet-Draft will expire on September 12, 2019. +Copyright Notice + Copyright (c) 2019 IETF Trust and the persons identified as the + document authors. All rights reserved. + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. - - - -Schoenebeck Expires January 16, 2016 [Page 1] +Schoenebeck Expires September 12, 2019 [Page 1] -Internet-Draft LinuxSampler Control Protocol July 2015 +Internet-Draft LinuxSampler Control Protocol March 2019 + + This document may not be modified, and derivative works of it may not + be created, and it may not be published except as an Internet-Draft. Table of Contents - 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 7 - 2. Versioning of this specification . . . . . . . . . . . . . . 8 - 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 9 - 4. Focus of this protocol . . . . . . . . . . . . . . . . . . . 10 - 5. Communication Overview . . . . . . . . . . . . . . . . . . . 11 - 5.1. Request/response communication method . . . . . . . . . . 11 - 5.1.1. Result format . . . . . . . . . . . . . . . . . . . 12 - 5.2. Subscribe/notify communication method . . . . . . . . . . 14 - 6. Description for control commands . . . . . . . . . . . . . . 16 - 6.1. Ignored lines and comments . . . . . . . . . . . . . . . 16 - 6.2. Configuring audio drivers . . . . . . . . . . . . . . . . 16 - 6.2.1. Getting amount of available audio output drivers . . 17 - 6.2.2. Getting all available audio output drivers . . . . . 17 - 6.2.3. Getting information about a specific audio output - driver . . . . . . . . . . . . . . . . . . . . . . . 17 - 6.2.4. Getting information about specific audio output - driver parameter . . . . . . . . . . . . . . . . . . 18 - 6.2.5. Creating an audio output device . . . . . . . . . . 22 - 6.2.6. Destroying an audio output device . . . . . . . . . 23 - 6.2.7. Getting all created audio output device count . . . 24 - 6.2.8. Getting all created audio output device list . . . . 24 - 6.2.9. Getting current settings of an audio output device . 24 - 6.2.10. Changing settings of audio output devices . . . . . 26 - 6.2.11. Getting information about an audio channel . . . . . 27 - 6.2.12. Getting information about specific audio channel - parameter . . . . . . . . . . . . . . . . . . . . . 28 - 6.2.13. Changing settings of audio output channels . . . . . 30 - 6.3. Configuring MIDI input drivers . . . . . . . . . . . . . 31 - 6.3.1. Getting amount of available MIDI input drivers . . . 32 - 6.3.2. Getting all available MIDI input drivers . . . . . . 32 - 6.3.3. Getting information about a specific MIDI input - driver . . . . . . . . . . . . . . . . . . . . . . . 33 - 6.3.4. Getting information about specific MIDI input - driver parameter . . . . . . . . . . . . . . . . . . 34 - 6.3.5. Creating a MIDI input device . . . . . . . . . . . . 36 - 6.3.6. Destroying a MIDI input device . . . . . . . . . . . 37 - 6.3.7. Getting all created MIDI input device count . . . . 38 - 6.3.8. Getting all created MIDI input device list . . . . . 38 - 6.3.9. Getting current settings of a MIDI input device . . 39 - 6.3.10. Changing settings of MIDI input devices . . . . . . 40 - 6.3.11. Getting information about a MIDI port . . . . . . . 40 - 6.3.12. Getting information about specific MIDI port - parameter . . . . . . . . . . . . . . . . . . . . . 41 - 6.3.13. Changing settings of MIDI input ports . . . . . . . 43 - 6.4. Configuring sampler channels . . . . . . . . . . . . . . 44 - 6.4.1. Loading an instrument . . . . . . . . . . . . . . . 44 - - - -Schoenebeck Expires January 16, 2016 [Page 2] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - - 6.4.2. Loading a sampler engine . . . . . . . . . . . . . . 45 - 6.4.3. Getting all created sampler channel count . . . . . 46 - 6.4.4. Getting all created sampler channel list . . . . . . 47 - 6.4.5. Adding a new sampler channel . . . . . . . . . . . . 47 - 6.4.6. Removing a sampler channel . . . . . . . . . . . . . 48 - 6.4.7. Getting amount of available engines . . . . . . . . 49 - 6.4.8. Getting all available engines . . . . . . . . . . . 49 - 6.4.9. Getting information about an engine . . . . . . . . 49 - 6.4.10. Getting sampler channel information . . . . . . . . 51 - 6.4.11. Current number of active voices . . . . . . . . . . 54 - 6.4.12. Current number of active disk streams . . . . . . . 55 - 6.4.13. Current fill state of disk stream buffers . . . . . 55 - 6.4.14. Setting audio output device . . . . . . . . . . . . 56 - 6.4.15. Setting audio output type . . . . . . . . . . . . . 57 - 6.4.16. Setting audio output channel . . . . . . . . . . . . 58 - 6.4.17. Add MIDI input to sampler channel . . . . . . . . . 59 - 6.4.18. Remove MIDI input(s) from sampler channel . . . . . 60 - 6.4.19. Getting all MIDI inputs of a sampler channel . . . . 61 - 6.4.20. Setting MIDI input device . . . . . . . . . . . . . 62 - 6.4.21. Setting MIDI input type . . . . . . . . . . . . . . 63 - 6.4.22. Setting MIDI input port . . . . . . . . . . . . . . 64 - 6.4.23. Setting MIDI input channel . . . . . . . . . . . . . 65 - 6.4.24. Setting channel volume . . . . . . . . . . . . . . . 66 - 6.4.25. Muting a sampler channel . . . . . . . . . . . . . . 66 - 6.4.26. Soloing a sampler channel . . . . . . . . . . . . . 67 - 6.4.27. Assigning a MIDI instrument map to a sampler - channel . . . . . . . . . . . . . . . . . . . . . . 68 - 6.4.28. Adding an effect send to a sampler channel . . . . . 69 - 6.4.29. Removing an effect send from a sampler channel . . . 70 - 6.4.30. Getting amount of effect sends on a sampler - channel . . . . . . . . . . . . . . . . . . . . . . 71 - 6.4.31. Listing all effect sends on a sampler channel . . . 71 - 6.4.32. Getting effect send information . . . . . . . . . . 72 - 6.4.33. Changing effect send's name . . . . . . . . . . . . 74 - 6.4.34. Altering effect send's audio routing . . . . . . . . 75 - 6.4.35. Assigning destination effect to an effect send . . . 76 - 6.4.36. Removing destination effect from an effect send . . 77 - 6.4.37. Altering effect send's MIDI controller . . . . . . . 77 - 6.4.38. Altering effect send's send level . . . . . . . . . 78 - 6.4.39. Sending MIDI messages to sampler channel . . . . . . 79 - 6.4.40. Resetting a sampler channel . . . . . . . . . . . . 80 - 6.5. Controlling connection . . . . . . . . . . . . . . . . . 81 - 6.5.1. Register front-end for receiving event messages . . 81 - 6.5.2. Unregister front-end for not receiving event - messages . . . . . . . . . . . . . . . . . . . . . . 81 - 6.5.3. Enable or disable echo of commands . . . . . . . . . 82 - 6.5.4. Close client connection . . . . . . . . . . . . . . 83 - 6.6. Global commands . . . . . . . . . . . . . . . . . . . . . 83 - - - -Schoenebeck Expires January 16, 2016 [Page 3] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - - 6.6.1. Current number of active voices . . . . . . . . . . 83 - 6.6.2. Maximum amount of active voices . . . . . . . . . . 83 - 6.6.3. Current number of active disk streams . . . . . . . 83 - 6.6.4. Reset sampler . . . . . . . . . . . . . . . . . . . 84 - 6.6.5. General sampler informations . . . . . . . . . . . . 84 - 6.6.6. Getting global volume attenuation . . . . . . . . . 85 - 6.6.7. Setting global volume attenuation . . . . . . . . . 86 - 6.6.8. Getting global voice limit . . . . . . . . . . . . . 86 - 6.6.9. Setting global voice limit . . . . . . . . . . . . . 87 - 6.6.10. Getting global disk stream limit . . . . . . . . . . 87 - 6.6.11. Setting global disk stream limit . . . . . . . . . . 88 - 6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 88 - 6.7.1. Create a new MIDI instrument map . . . . . . . . . . 89 - 6.7.2. Delete one particular or all MIDI instrument maps . 90 - 6.7.3. Get amount of existing MIDI instrument maps . . . . 91 - 6.7.4. Getting all created MIDI instrument maps . . . . . . 91 - 6.7.5. Getting MIDI instrument map information . . . . . . 91 - 6.7.6. Renaming a MIDI instrument map . . . . . . . . . . . 92 - 6.7.7. Create or replace a MIDI instrument map entry . . . 93 - 6.7.8. Getting amount of MIDI instrument map entries . . . 96 - 6.7.9. Getting indeces of all entries of a MIDI - instrument map . . . . . . . . . . . . . . . . . . . 96 - 6.7.10. Remove an entry from the MIDI instrument map . . . . 97 - 6.7.11. Get current settings of MIDI instrument map entry . 98 - 6.7.12. Clear MIDI instrument map . . . . . . . . . . . . . 99 - 6.8. Managing Instruments Database . . . . . . . . . . . . . . 100 - 6.8.1. Creating a new instrument directory . . . . . . . . 100 - 6.8.2. Deleting an instrument directory . . . . . . . . . . 101 - 6.8.3. Getting amount of instrument directories . . . . . . 102 - 6.8.4. Listing all directories in specific directory . . . 102 - 6.8.5. Getting instrument directory information . . . . . . 103 - 6.8.6. Renaming an instrument directory . . . . . . . . . . 104 - 6.8.7. Moving an instrument directory . . . . . . . . . . . 104 - 6.8.8. Copying instrument directories . . . . . . . . . . . 105 - 6.8.9. Changing the description of directory . . . . . . . 106 - 6.8.10. Finding directories . . . . . . . . . . . . . . . . 106 - 6.8.11. Adding instruments to the instruments database . . . 108 - 6.8.12. Removing an instrument . . . . . . . . . . . . . . . 109 - 6.8.13. Getting amount of instruments . . . . . . . . . . . 110 - 6.8.14. Listing all instruments in specific directory . . . 111 - 6.8.15. Getting instrument information . . . . . . . . . . . 111 - 6.8.16. Renaming an instrument . . . . . . . . . . . . . . . 114 - 6.8.17. Moving an instrument . . . . . . . . . . . . . . . . 114 - 6.8.18. Copying instruments . . . . . . . . . . . . . . . . 115 - 6.8.19. Changing the description of instrument . . . . . . . 115 - 6.8.20. Finding instruments . . . . . . . . . . . . . . . . 116 - 6.8.21. Getting job status information . . . . . . . . . . . 118 - 6.8.22. Formatting the instruments database . . . . . . . . 120 - - - -Schoenebeck Expires January 16, 2016 [Page 4] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - - 6.8.23. Checking for lost instrument files . . . . . . . . . 120 - 6.8.24. Replacing an instrument file . . . . . . . . . . . . 121 - 6.9. Editing Instruments . . . . . . . . . . . . . . . . . . . 121 - 6.9.1. Opening an appropriate instrument editor - application . . . . . . . . . . . . . . . . . . . . 121 - 6.10. Managing Files . . . . . . . . . . . . . . . . . . . . . 122 - 6.10.1. Retrieving amount of instruments of a file . . . . . 123 - 6.10.2. Retrieving all instruments of a file . . . . . . . . 123 - 6.10.3. Retrieving informations about one instrument in a - file . . . . . . . . . . . . . . . . . . . . . . . . 124 - 6.11. Managing Effects . . . . . . . . . . . . . . . . . . . . 126 - 6.11.1. Retrieve amount of available effects . . . . . . . . 126 - 6.11.2. Get list of available effects . . . . . . . . . . . 127 - 6.11.3. Retrieving general information about an effect . . . 127 - 6.11.4. Creating an instance of an effect by its portable - ID . . . . . . . . . . . . . . . . . . . . . . . . . 128 - 6.11.5. Creating an instance of an effect by its - numerical ID . . . . . . . . . . . . . . . . . . . . 129 - 6.11.6. Destroy an effect instance . . . . . . . . . . . . . 130 - 6.11.7. Retrieve amount of effect instances . . . . . . . . 131 - 6.11.8. Get list of effect instances . . . . . . . . . . . . 131 + 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 6 + 2. Versioning of this specification . . . . . . . . . . . . . . 7 + 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 + 4. Focus of this protocol . . . . . . . . . . . . . . . . . . . 8 + 5. Communication Overview . . . . . . . . . . . . . . . . . . . 8 + 5.1. Request/response communication method . . . . . . . . . . 9 + 5.1.1. Result format . . . . . . . . . . . . . . . . . . . . 9 + 5.2. Subscribe/notify communication method . . . . . . . . . . 12 + 6. Description for control commands . . . . . . . . . . . . . . 13 + 6.1. Ignored lines and comments . . . . . . . . . . . . . . . 14 + 6.2. Configuring audio drivers . . . . . . . . . . . . . . . . 14 + 6.2.1. Getting amount of available audio output drivers . . 14 + 6.2.2. Getting all available audio output drivers . . . . . 15 + 6.2.3. Getting information about a specific audio + output 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 . . . . 21 + 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 . . . . . . 23 + 6.2.11. Getting information about an audio channel . . . . . 24 + 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 . . . 29 + 6.3.2. Getting all available MIDI input drivers . . . . . . 30 + 6.3.3. Getting information about a specific MIDI input + driver . . . . . . . . . . . . . . . . . . . . . . . 30 + 6.3.4. Getting information about specific MIDI input driver + parameter . . . . . . . . . . . . . . . . . . . . . . 31 + 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 . . . . . 35 + 6.3.8. Getting all created MIDI input device list . . . . . 36 + 6.3.9. Getting current settings of a MIDI input device . . . 36 + 6.3.10. Changing settings of MIDI input devices . . . . . . . 37 + 6.3.11. Getting information about a MIDI port . . . . . . . . 38 + 6.3.12. Getting information about specific MIDI port + parameter . . . . . . . . . . . . . . . . . . . . . . 39 + + + +Schoenebeck Expires September 12, 2019 [Page 2] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + + 6.3.13. Changing settings of MIDI input ports . . . . . . . . 41 + 6.4. Configuring sampler channels . . . . . . . . . . . . . . 41 + 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 . . . . . . . . . . . 52 + 6.4.12. Current number of active disk streams . . . . . . . . 52 + 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 . . . . . . . . . . . . . . 54 + 6.4.16. Setting audio output channel . . . . . . . . . . . . 55 + 6.4.17. Add MIDI input to sampler channel . . . . . . . . . . 56 + 6.4.18. Remove MIDI input(s) from sampler channel . . . . . . 57 + 6.4.19. Getting all MIDI inputs of a sampler channel . . . . 58 + 6.4.20. Setting MIDI input device . . . . . . . . . . . . . . 59 + 6.4.21. Setting MIDI input type . . . . . . . . . . . . . . . 60 + 6.4.22. Setting MIDI input port . . . . . . . . . . . . . . . 61 + 6.4.23. Setting MIDI input channel . . . . . . . . . . . . . 62 + 6.4.24. Setting channel volume . . . . . . . . . . . . . . . 63 + 6.4.25. Muting a sampler channel . . . . . . . . . . . . . . 63 + 6.4.26. Soloing a sampler channel . . . . . . . . . . . . . . 64 + 6.4.27. Assigning a MIDI instrument map to a sampler channel 65 + 6.4.28. Adding an effect send to a sampler channel . . . . . 66 + 6.4.29. Removing an effect send from a sampler channel . . . 67 + 6.4.30. Getting amount of effect sends on a sampler channel . 68 + 6.4.31. Listing all effect sends on a sampler channel . . . . 68 + 6.4.32. Getting effect send information . . . . . . . . . . . 69 + 6.4.33. Changing effect send's name . . . . . . . . . . . . . 71 + 6.4.34. Altering effect send's audio routing . . . . . . . . 71 + 6.4.35. Assigning destination effect to an effect send . . . 73 + 6.4.36. Removing destination effect from an effect send . . . 74 + 6.4.37. Altering effect send's MIDI controller . . . . . . . 74 + 6.4.38. Altering effect send's send level . . . . . . . . . . 75 + 6.4.39. Sending MIDI messages to sampler channel . . . . . . 76 + 6.4.40. Resetting a sampler channel . . . . . . . . . . . . . 77 + 6.5. Controlling connection . . . . . . . . . . . . . . . . . 78 + 6.5.1. Register front-end for receiving event messages . . . 78 + 6.5.2. Unregister front-end for not receiving event messages 78 + 6.5.3. Enable or disable echo of commands . . . . . . . . . 79 + 6.5.4. Close client connection . . . . . . . . . . . . . . . 80 + 6.6. Global commands . . . . . . . . . . . . . . . . . . . . . 80 + + + +Schoenebeck Expires September 12, 2019 [Page 3] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + + 6.6.1. Current number of active voices . . . . . . . . . . . 80 + 6.6.2. Maximum amount of active voices . . . . . . . . . . . 80 + 6.6.3. Current number of active disk streams . . . . . . . . 80 + 6.6.4. Reset sampler . . . . . . . . . . . . . . . . . . . . 81 + 6.6.5. General sampler information . . . . . . . . . . . . . 81 + 6.6.6. Getting global volume attenuation . . . . . . . . . . 82 + 6.6.7. Setting global volume attenuation . . . . . . . . . . 83 + 6.6.8. Getting global voice limit . . . . . . . . . . . . . 83 + 6.6.9. Setting global voice limit . . . . . . . . . . . . . 84 + 6.6.10. Getting global disk stream limit . . . . . . . . . . 84 + 6.6.11. Setting global disk stream limit . . . . . . . . . . 85 + 6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 85 + 6.7.1. Create a new MIDI instrument map . . . . . . . . . . 86 + 6.7.2. Delete one particular or all MIDI instrument maps . . 87 + 6.7.3. Get amount of existing MIDI instrument maps . . . . . 88 + 6.7.4. Getting all created MIDI instrument maps . . . . . . 88 + 6.7.5. Getting MIDI instrument map information . . . . . . . 88 + 6.7.6. Renaming a MIDI instrument map . . . . . . . . . . . 89 + 6.7.7. Create or replace a MIDI instrument map entry . . . . 90 + 6.7.8. Getting amount of MIDI instrument map entries . . . . 93 + 6.7.9. Getting indeces of all entries of a MIDI instrument + map . . . . . . . . . . . . . . . . . . . . . . . . . 93 + 6.7.10. Remove an entry from the MIDI instrument map . . . . 94 + 6.7.11. Get current settings of MIDI instrument map entry . . 95 + 6.7.12. Clear MIDI instrument map . . . . . . . . . . . . . . 96 + 6.8. Managing Instruments Database . . . . . . . . . . . . . . 97 + 6.8.1. Creating a new instrument directory . . . . . . . . . 97 + 6.8.2. Deleting an instrument directory . . . . . . . . . . 98 + 6.8.3. Getting amount of instrument directories . . . . . . 99 + 6.8.4. Listing all directories in specific directory . . . . 99 + 6.8.5. Getting instrument directory information . . . . . . 100 + 6.8.6. Renaming an instrument directory . . . . . . . . . . 101 + 6.8.7. Moving an instrument directory . . . . . . . . . . . 101 + 6.8.8. Copying instrument directories . . . . . . . . . . . 102 + 6.8.9. Changing the description of directory . . . . . . . . 103 + 6.8.10. Finding directories . . . . . . . . . . . . . . . . . 103 + 6.8.11. Adding instruments to the instruments database . . . 104 + 6.8.12. Removing an instrument . . . . . . . . . . . . . . . 106 + 6.8.13. Getting amount of instruments . . . . . . . . . . . . 106 + 6.8.14. Listing all instruments in specific directory . . . . 107 + 6.8.15. Getting instrument information . . . . . . . . . . . 107 + 6.8.16. Renaming an instrument . . . . . . . . . . . . . . . 110 + 6.8.17. Moving an instrument . . . . . . . . . . . . . . . . 110 + 6.8.18. Copying instruments . . . . . . . . . . . . . . . . . 111 + 6.8.19. Changing the description of instrument . . . . . . . 112 + 6.8.20. Finding instruments . . . . . . . . . . . . . . . . . 112 + 6.8.21. Getting job status information . . . . . . . . . . . 113 + 6.8.22. Formatting the instruments database . . . . . . . . . 114 + + + +Schoenebeck Expires September 12, 2019 [Page 4] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + + 6.8.23. Checking for lost instrument files . . . . . . . . . 115 + 6.8.24. Replacing an instrument file . . . . . . . . . . . . 115 + 6.9. Editing Instruments . . . . . . . . . . . . . . . . . . . 116 + 6.9.1. Opening an appropriate instrument editor application 116 + 6.10. Managing Files . . . . . . . . . . . . . . . . . . . . . 117 + 6.10.1. Retrieving amount of instruments of a file . . . . . 117 + 6.10.2. Retrieving all instruments of a file . . . . . . . . 118 + 6.10.3. Retrieving information about one instrument in a + file . . . . . . . . . . . . . . . . . . . . . . . . 118 + 6.11. Managing Effects . . . . . . . . . . . . . . . . . . . . 120 + 6.11.1. Retrieve amount of available effects . . . . . . . . 121 + 6.11.2. Get list of available effects . . . . . . . . . . . 121 + 6.11.3. Retrieving general information about an effect . . . 122 + 6.11.4. Creating an instance of an effect by its portable ID 123 + 6.11.5. Creating an instance of an effect by its numerical + ID . . . . . . . . . . . . . . . . . . . . . . . . . 124 + 6.11.6. Destroy an effect instance . . . . . . . . . . . . . 125 + 6.11.7. Retrieve amount of effect instances . . . . . . . . 126 + 6.11.8. Get list of effect instances . . . . . . . . . . . . 126 6.11.9. Retrieving current information about an effect - instance . . . . . . . . . . . . . . . . . . . . . . 132 - 6.11.10. Retrieving information about an effect parameter . . 133 - 6.11.11. Altering an effect parameter . . . . . . . . . . . . 135 - 6.11.12. Retrieve amount of send effect chains . . . . . . . 135 - 6.11.13. Retrieve list of send effect chains . . . . . . . . 136 - 6.11.14. Add send effect chain . . . . . . . . . . . . . . . 136 - 6.11.15. Remove send effect chain . . . . . . . . . . . . . . 137 - 6.11.16. Retrieving information about a send effect chain . . 138 - 6.11.17. Append effect instance to a send effect chain . . . 139 - 6.11.18. Insert effect instance to a send effect chain . . . 139 - 6.11.19. Remove effect instance from send effect chain . . . 140 - 7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . 142 - 7.1. Character Set and Escape Sequences . . . . . . . . . . . 159 - 8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 - 8.1. Number of audio output devices changed . . . . . . . . . 164 - 8.2. Audio output device's settings changed . . . . . . . . . 164 - 8.3. Number of MIDI input devices changed . . . . . . . . . . 164 - 8.4. MIDI input device's settings changed . . . . . . . . . . 165 - 8.5. Number of sampler channels changed . . . . . . . . . . . 165 - 8.6. MIDI data on a sampler channel arrived . . . . . . . . . 165 - 8.7. MIDI data on a MIDI input device arrived . . . . . . . . 166 - 8.8. Number of active voices changed . . . . . . . . . . . . . 166 - 8.9. Number of active disk streams changed . . . . . . . . . . 167 - 8.10. Disk stream buffer fill state changed . . . . . . . . . . 167 - 8.11. Channel information changed . . . . . . . . . . . . . . . 167 - 8.12. Number of effect sends changed . . . . . . . . . . . . . 168 - - - -Schoenebeck Expires January 16, 2016 [Page 5] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - - 8.13. Effect send information changed . . . . . . . . . . . . . 168 - 8.14. Total number of active voices changed . . . . . . . . . . 169 - 8.15. Total number of active disk streams changed . . . . . . . 169 - 8.16. Number of MIDI instrument maps changed . . . . . . . . . 169 - 8.17. MIDI instrument map information changed . . . . . . . . . 169 - 8.18. Number of MIDI instruments changed . . . . . . . . . . . 170 - 8.19. MIDI instrument information changed . . . . . . . . . . . 170 - 8.20. Global settings changed . . . . . . . . . . . . . . . . . 171 - 8.21. Number of database instrument directories changed . . . . 171 - 8.22. Database instrument directory information changed . . . . 171 - 8.23. Number of database instruments changed . . . . . . . . . 172 - 8.24. Database instrument information changed . . . . . . . . . 172 - 8.25. Database job status information changed . . . . . . . . . 173 - 8.26. Number of effect instances changed . . . . . . . . . . . 173 - 8.27. Effect instance information changed . . . . . . . . . . . 174 - 8.28. Number of send effect chains changed . . . . . . . . . . 174 - 8.29. Send effect chain information changed . . . . . . . . . . 174 - 8.30. Miscellaneous and debugging events . . . . . . . . . . . 175 - 9. Security Considerations . . . . . . . . . . . . . . . . . . . 176 - 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 177 - 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 178 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 179 - Intellectual Property and Copyright Statements . . . . . . . . . 180 - - - - - - - - - - - + instance . . . . . . . . . . . . . . . . . . . . . . 126 + 6.11.10. Retrieving information about an effect parameter . . 128 + 6.11.11. Altering an effect parameter . . . . . . . . . . . . 130 + 6.11.12. Retrieve amount of send effect chains . . . . . . . 130 + 6.11.13. Retrieve list of send effect chains . . . . . . . . 131 + 6.11.14. Add send effect chain . . . . . . . . . . . . . . . 131 + 6.11.15. Remove send effect chain . . . . . . . . . . . . . . 132 + 6.11.16. Retrieving information about a send effect chain . . 132 + 6.11.17. Append effect instance to a send effect chain . . . 133 + 6.11.18. Insert effect instance to a send effect chain . . . 134 + 6.11.19. Remove effect instance from send effect chain . . . 135 + 7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . 136 + 7.1. Character Set and Escape Sequences . . . . . . . . . . . 153 + 8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 + 8.1. Number of audio output devices changed . . . . . . . . . 157 + 8.2. Audio output device's settings changed . . . . . . . . . 157 + 8.3. Number of MIDI input devices changed . . . . . . . . . . 157 + 8.4. MIDI input device's settings changed . . . . . . . . . . 158 + 8.5. Number of sampler channels changed . . . . . . . . . . . 158 + 8.6. MIDI data on a sampler channel arrived . . . . . . . . . 158 + 8.7. MIDI data on a MIDI input device arrived . . . . . . . . 159 + 8.8. Number of active voices changed . . . . . . . . . . . . . 159 + 8.9. Number of active disk streams changed . . . . . . . . . . 160 + 8.10. Disk stream buffer fill state changed . . . . . . . . . . 160 + 8.11. Channel information changed . . . . . . . . . . . . . . . 160 + 8.12. Number of effect sends changed . . . . . . . . . . . . . 161 + 8.13. Effect send information changed . . . . . . . . . . . . . 161 + 8.14. Total number of active voices changed . . . . . . . . . . 162 - - - - - - - - - - - - - - -Schoenebeck Expires January 16, 2016 [Page 6] - -Internet-Draft LinuxSampler Control Protocol July 2015 - +Schoenebeck Expires September 12, 2019 [Page 5] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + + 8.15. Total number of active disk streams changed . . . . . . . 162 + 8.16. Number of MIDI instrument maps changed . . . . . . . . . 162 + 8.17. MIDI instrument map information changed . . . . . . . . . 162 + 8.18. Number of MIDI instruments changed . . . . . . . . . . . 163 + 8.19. MIDI instrument information changed . . . . . . . . . . . 163 + 8.20. Global settings changed . . . . . . . . . . . . . . . . . 164 + 8.21. Number of database instrument directories changed . . . . 164 + 8.22. Database instrument directory information changed . . . . 165 + 8.23. Number of database instruments changed . . . . . . . . . 165 + 8.24. Database instrument information changed . . . . . . . . . 166 + 8.25. Database job status information changed . . . . . . . . . 166 + 8.26. Number of effect instances changed . . . . . . . . . . . 167 + 8.27. Effect instance information changed . . . . . . . . . . . 167 + 8.28. Number of send effect chains changed . . . . . . . . . . 167 + 8.29. Send effect chain information changed . . . . . . . . . . 168 + 8.30. Miscellaneous and debugging events . . . . . . . . . . . 168 + 9. Security Considerations . . . . . . . . . . . . . . . . . . . 168 + 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 168 + 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 169 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 169 1. Requirements notation @@ -354,7 +320,7 @@ C: "some line" - "another line" + "another line" must actually be interpreted as client sending the following message: @@ -363,6 +329,15 @@ where symbolizes the carriage return character and the line feed character as defined in the ASCII standard. + + + + +Schoenebeck Expires September 12, 2019 [Page 6] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + Due to technical reasons, messages can arbitrary be fragmented, means the following example: @@ -384,15 +359,6 @@ where again and symbolize the carriage return and line feed characters respectively. - - - - -Schoenebeck Expires January 16, 2016 [Page 7] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - 2. Versioning of this specification LSCP will certainly be extended and enhanced by-and-by. Each @@ -418,37 +384,20 @@ 2. The frontend's LSCP minor version is less or equal than the sampler's LSCP minor version. - Compatibility can only be claimed if both rules are true. The - frontend can use the "GET SERVER INFO" (Section 6.6.5) command to get - the version of the LSCP specification the sampler complies with. - - - - - - - - - - - - - - - - - - -Schoenebeck Expires January 16, 2016 [Page 8] +Schoenebeck Expires September 12, 2019 [Page 7] -Internet-Draft LinuxSampler Control Protocol July 2015 +Internet-Draft LinuxSampler Control Protocol March 2019 + Compatibility can only be claimed if both rules are true. The + frontend can use the "GET SERVER INFO" (Section 6.6.5) command to get + the version of the LSCP specification the sampler complies with. + 3. Introduction LinuxSampler is a so called software sampler application capable to @@ -459,7 +408,7 @@ virtual channels which will be referred in this document as "sampler channels". The channels are in such way virtual as they can be connected to an arbitrary MIDI input method and arbitrary MIDI - channel (e.g. sampler channel 17 could be connected to an ALSA + channel (e.g. sampler channel 17 could be connected to an ALSA sequencer device 64:0 and listening to MIDI channel 1 there). Each sampler channel will be associated with an instance of one of the available sampler engines (e.g. GigEngine, DLSEngine). The audio @@ -467,44 +416,6 @@ output method (ALSA / JACK) and an arbitrary audio output channel there. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Schoenebeck Expires January 16, 2016 [Page 9] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - 4. Focus of this protocol Main focus of this protocol is to provide a way to configure a @@ -515,52 +426,6 @@ covered by MIDI or which may at most be handled via MIDI System Exclusive Messages. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Schoenebeck Expires January 16, 2016 [Page 10] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - 5. Communication Overview There are two distinct methods of communication between a running @@ -573,6 +438,18 @@ more effort to be implemented in the front-end application. The two communication methods will be described next. + + + + + + + +Schoenebeck Expires September 12, 2019 [Page 8] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + 5.1. Request/response communication method This simple communication method is based on TCP [RFC793]. The @@ -610,13 +487,6 @@ server they MUST be processed in the order they were received and result sets MUST be sent back in the same order. - - -Schoenebeck Expires January 16, 2016 [Page 11] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - 5.1.1. Result format Result set could be one of the following types: @@ -627,6 +497,15 @@ 3. Error + + + + +Schoenebeck Expires September 12, 2019 [Page 9] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + Warning and Error result sets MUST be single line and have the following format: @@ -665,14 +544,6 @@ Empty result set is issued when the server only needed to acknowledge the fact that the request was received and it was processed successfully and no additional information is available. This result - - - -Schoenebeck Expires January 16, 2016 [Page 12] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - set has the following format: "OK" @@ -683,6 +554,14 @@ S: "OK" + + + +Schoenebeck Expires September 12, 2019 [Page 10] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + Single line result sets are command specific. One example of a single line result set is an empty line. Multi-line result sets are command specific and may include one or more lines of information. @@ -696,19 +575,19 @@ S: "DRIVER: ALSA" - "CHANNELS: 2" + "CHANNELS: 2" - "SAMPLERATE: 44100" + "SAMPLERATE: 44100" - "ACTIVE: true" + "ACTIVE: true" - "FRAGMENTS: 2" + "FRAGMENTS: 2" - "FRAGMENTSIZE: 128" + "FRAGMENTSIZE: 128" - "CARD: '0,0'" + "CARD: '0,0'" - "." + "." In addition to above mentioned formats, warnings and empty result sets MAY be indexed. In this case, they have the following formats @@ -721,14 +600,6 @@ where is command specific and is used to indicate channel number that the result set was related to or other integer value. - - - -Schoenebeck Expires January 16, 2016 [Page 13] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - Each line of the result set MUST end with . Examples: @@ -739,6 +610,14 @@ C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000" + + + +Schoenebeck Expires September 12, 2019 [Page 11] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + S: "WRN[0]:32:Sample rate not supported, using 44100 instead." 5.2. Subscribe/notify communication method @@ -777,14 +656,6 @@ 3. When response is being sent to the client, event MUST be inserted in the stream before or after the response, but NOT in the middle. Same is true about the response. It should never be - - - -Schoenebeck Expires January 16, 2016 [Page 14] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - inserted in the middle of the event message as well as any other response. @@ -793,6 +664,16 @@ UNSUBSCRIBE + + + + + +Schoenebeck Expires September 12, 2019 [Page 12] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + where will be replace by the respective event that client is no longer interested in receiving. For a list of supported events see Section 8. @@ -830,17 +711,6 @@ reconnects it MUST resubscribe to all events that it wants to receive. - - - - - - -Schoenebeck Expires January 16, 2016 [Page 15] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - 6. Description for control commands This chapter will describe the available control commands that can be @@ -850,6 +720,16 @@ LinuxSampler signals the end of the response by a "." (single dot) line. + + + + + +Schoenebeck Expires September 12, 2019 [Page 13] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + 6.1. Ignored lines and comments White lines, that is lines which only contain space and tabulator @@ -886,17 +766,6 @@ retrieve what parameters drivers are offering, how to retrieve their possible values, etc. - - - - - - -Schoenebeck Expires January 16, 2016 [Page 16] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - 6.2.1. Getting amount of available audio output drivers Use the following command to get the number of audio output drivers @@ -909,6 +778,14 @@ LinuxSampler will answer by sending the number of audio output drivers. + + + +Schoenebeck Expires September 12, 2019 [Page 14] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + Example: C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS" @@ -946,13 +823,6 @@ Possible Answers: - - -Schoenebeck Expires January 16, 2016 [Page 17] - -Internet-Draft LinuxSampler Control Protocol July 2015 - - LinuxSampler will answer by sending a separated list. Each answer line begins with the information category name followed by a colon and then a space character and finally the info @@ -965,6 +835,13 @@ character string describing the audio output driver + + +Schoenebeck Expires September 12, 2019 [Page 15] + +Internet-Draft LinuxSampler Control Protocol March 2019 + + VERSION - character string reflecting the driver's version @@ -984,12 +861,12 @@ S: "DESCRIPTION: Advanced Linux Sound Architecture" - "VERSION: 1.0" + "VERSION: 1.0" - "PARAMETERS: DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS, + "PARAMETERS: DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS, FRAGMENTSIZE,CARD" - "." + "." 6.2.4. Getting information about specific audio output driver parameter @@ -1001,14 +878,6 @@ Where