No internet connection
  1. Home
  2. How to

Searching for SoundFlow Commands / API etc, Documentation Project.

By Tony David Cray @tdc
    2022-03-30 01:40:51.957Z

    Hi Folks,

    I am having quite a challenging time working out how to achieve desired results here at present, and thought I would check in here with the forums to find out if this is just a current limitation or if I not using the system properly.

    Finding how to construct even the most simple of tasks is difficult as no results appear from a search, and usually requires some forum diving to find some scripts. Searching the API is daunting do to the sheer number of entries, and then they often don't correlate to how a script is required to be structures.

    A few examples:

    Send a MIDI CC Message
    • Searching the Macro's results in nothing.
    • Searching in Script's results in only Pro Tools commands, not the raw macro to be able to send a MIDI message.
    • Searching the API for MIDI or SEND results in many definitions that hint at sending, and are useful once you have your script in place and would like to know more about the definition, but nothing to help with formatting the actual javascript. e.g https://soundflow.org/docs/api/interfaces/midisendactionargs#externalmidiport

    Initiate a User Prompt
    • Searching results in nothing at all. No macros or scripts.

    The Javascript code-completion is certainly a great assistance in the editor, but not at the very start of the journey.

    There really needs to be a Package of raw building blocks that comprises of Script's, Macro's, Template's, Deck's, Surface's for as many functions as possible. Each item would make use of the Documentation tab to explain the function's use and options. Does this already exist and I have somehow missed it? Or is this something we need to make into a project?

    Thanks, Tony.

    Reply
    • 7 replies
    1. Kitch Membery @Kitch2022-03-30 03:14:45.214Z

      Hi @tdc,

      Thanks for asking. I'll attempt to answer some of your questions in more detail later, but for now I'll point you in the right direction for Sending a midi CC message.

      First start by creating a macro.

      To do this Click the "New" button in the Editor tab and select "Macro", then name the macro and press return.

      Once the Macro editor appears click the "Add action" button.

      This will bring up a list of macro actions that you can choose from which are essentially building blocks that you can use to create a workflow.

      You mentioned in your post that you'd like to send a MIDI CC message, So start typing "MIDI CC" into the search field.

      When the "Send MIDI CC" macro action appears, select it and it will be added to the macro.

      Then you can then taylor the macro actions properties as you wish.

      If you want to convert the Macro into a script you can click the "Convert to script button" in the header of the macro.

      Or you can click the three dots in the top right of the macro action and copy the macro action to the clipboard (in javascript form) ready to be pasted into a script.

      You may also find some of the video tutorial videos in the Learning SoundFlow playlist on youtube helpful, here is the link;
      https://www.youtube.com/playlist?list=PLKWpZOwx5Z3jxnpNo_dQPhDQNRwp7DCNj

      I hope that helps.
      Rock on!

      Reply1 Like
      1. TTony David Cray @tdc
          2022-03-30 03:47:36.587Z

          Thanks Kitch,

          I appreciate the clarification, whilst I have watched all your vids ( a few times, they are a great resource btw ) I think this detail didn't sink in. So there is an additional class of objects called "Actions" that only appear when clicking "Add Action". I must be holding on to the Keyboard Maestro approach of having all methods available in a list sorted in categories. I can now see a bunch more actions appearing in my search results.

          TLDR - Is it me, or is there still some work to go on the documentation for SF?

          However, there appear to be no actions that relate to "Prompt" "User" or "Set Variable" (Only actions that have vars typed as boolean appear) What is the correct method to ascertain how to implement a User Prompt using the SF?

          For example, say I want to pop up a modal to the user to enter some data that will guide the following actions. I search for an action that might be appropriate, so I search the Add Action results for prompt, user, input and text and there are either no results or results that a related to other specific packages. ( Would be so helpful to have prefix's on these results indicating they are part of a specific package as opposed to the Core SF library.

          I choose the "Text Popup" action. and can see its asking for a Title. But, there is no information about what this action does, or how it should be used in context. Showing the advanced features I can see there is a property called "Popup Identifier" but no way to know what this is either.

          Converting to a Script I can see that its an sf.interaction.popupText function with an argument of Title. Right-clicking on the function I am offered to go to the Definition but clicking this doesn't do anything. Hovering over this I am shown that this method is part of the AutomationRootInteractionApi but I can't click on the green text that looks like it should link to the docs? So, I pop over to the API Docs and search for AutomationRootInteractionApi and finally find the PopupText methods. Unfortunately I am not sure that this is the method I want for asking the user to input data.

          Is it me, or is there still some work to go on the documentation for SF?

          With respect and admiration for what has been built with SF, Tony.

          Reply
          1. Kitch Membery @Kitch2022-03-30 04:29:16.329Z

            Thanks @tdc,

            I'm glad that helped. And thanks for the constructive feedback.

            There is a lot to cover in the above post so let me start by answering this;

            "Is it me, or is there still some work to go on the documentation for SF?"

            Yes there is most certainly, we are small team at the moment, but we have plans on adding to the documentation as soon as possible.

            When it comes to using more complex logic within SoundFlow, the script editor is going to be the best place to do this.

            Regarding setting variables, variables can be set using standard Javascript with the var, let and const key words.
            Here is a great place to learn about them; https://javascript.info/variables

            For creating user prompts you can use the prompt method. You can read more about the javascript prompt method and other interactions here https://javascript.info/alert-prompt-confirm.

            As an example, in the following script I'm prompting for a name then using log to display in the top right hand corner of the screen as a notification.

            const name = prompt("What is your name?")

log(name)

            "Would be so helpful to have prefix's on these results (macro actions) indicating they are part of a specific package as opposed to the Core SF library."

            That is a good point, for ideas like this be sure to add them to the Ideas section of the user forum, that way they can be logged and considered for future versions of SoundFlow.

            Hopefully once our documentation has improved, it will be easier to find these answers, but until then your best resource is the SoundFlow User Forum.

            :-)

            Reply
            1. TTony David Cray @tdc
                2022-03-30 05:56:09.462Z

                Thanks Kitch,

                Just to clarify my point a little further, its not raw Javascript that's the challenge, is knowing what is the correct method for SoundFlow that is ambiguous. I am experienced using JS and more than happy to develop the scripts in that environment, but its hard to know where to start. Is the "Jump to Definition" supposed to work in the editor ?

                I can appreciate the effort that developing the documentation would take, so perhaps you could implement a Wiki style documentation section for a "SF Core Objects" package that contains examples of macros / scripts / actions etc and allow the community to update and edit.

                Cheers.

                Reply
                1. Kitch Membery @Kitch2022-03-30 08:11:29.285Z

                  Hi @tdc,

                  My apologies at underestimating your Javascript knowledge. That's great, you have a head start on most of us.

                  I don't believe the "Jump to Definition" feature in the SoundFlow editor has been implemented... I'll have to check with Christian about that feature. I'll also pass the Wiki style documentation idea by him, although I believe he has a plan in place for approaching the SoundFlow documentation, when time permits.

                  I understand it's hard to know where to start, and we are always working on improving SoundFlow with every update. I'll keep an eye out in the forum for your posts, to hopefully steer you in the right direction to achieve the workflows you are after.

                  Thanks again for the input and feedback. :-)

                  Reply1 Like
                  1. TTony David Cray @tdc
                      2022-03-30 10:47:01.963Z

                      Thanks for your time and replies Kitch, I really appreciate it.

                      I wouldn't rate my JS skills anymore than my accounting skills.... but at least applying javascript to audio projects is rewarding. :-) My first few days with SoundFlow have convinced me that I need to join up and so will be doing so. I can see such potential of a platform like this.

                      01010010 01101111 01100011 01101011 00100000 01001111 01101110

                      Reply1 Like
                      1. Kitch Membery @Kitch2022-03-30 10:50:34.349Z

                        Sounds great Tony. And you’re welcome. :-)

                        I look forward to seeing your progress.

                        Rock on. :-)

                        Reply1 Like
            ReplyAdd progress note