Eisa's Portal » FAQ » (Technical) What are AudioX mini-API functions?
AudioX II
(Technical) What are AudioX mini-API functions?
AudioX II Mini-API 4.2.0

The AudioX II Mini-API is designed to allow other mod developers access to some of AudioX's features. This means that 3rd party UIs should be possible.

If you are a mod (aka add-on) developer and are interested in utilizing this mini-API then read on. If you aren't, then you may want to skip the details.


Important Changes

4.2.0 AX:API_Play changed to allow more control over whether samples should be played as music, as a sound effect or allow AudioX to decide.

3.3.37 Introduces pre-search keyword translations, which has resulted in the following changes:-
  • AX:API_Search() can optionally return results that include both the users and equivalent translated keyword(s) (where available).
  • AX:API_PageFooter() gets a 5th parameter (tsearch) for obtaining a translated search keyword.

3.3.29 consolidates several namespaces into one. In this process several API variables have been renamed as follows:-
  • AX.apiout -> AX.api_out
  • AX.CMD_SEARCH -> AX.s_CMD_SEARCH
  • AX.CMD_PGDN -> AX.s_CMD_PGDN
  • AX.CMD_PGUP -> AX.s_CMD_PGUP
  • AX.CMD_REFRESH -> AX.s_CMD_REFRESH
  • AX.CMD_MATCH -> AX.s_CMD_MATCH
  • AX.CMD_BEGIN -> AX.s_CMD_BEGIN


Mini-API Documentation
  • These functions will only be available once AudioX_Search has loaded.
  • If AX.api_out is true then AX:API_LineOut and AX:API_PageFooter are used for output. Please set AX.api_out to false when closing your mod's frame.
  • Be aware that AX.api_out toggles true/false with searches started by /ax commands and AX:API_Search.
  • AX.searchmode is used to store which table AudioX_Search and AudioX_UI are currently using. AudioX uses this variable extensively to point to the table by using _G[AX.searchmode] as a substitute for SoundLib and AUDIOX_FAVS. 3rd party UIs should adopt the same technique.
    NOTE: AX.searchmode is currently being filtered on this page by wowinterface. It's actually syntactic sugar for AX["searchmode"]. That is, AX. searchmode. (without any space after AX.)

  • function AX:API_ChatOutput()
    • Description:
      • Sets AX.api_out to false, redirecting output to the chatframe.
    • Note:
      • This function should be used instead of AX.api_out = false.
    • Example:
      • AX:API_ChatOutput()

  • function AX:API_UIOutput()
    • Description:
      • Sets AX.api_out to true, redirecting output to the UI.
    • Note:
      • This function should be used instead of AX.api_out = true.
    • Example:
      • AX:API_UIOutput()

  • function AX:API_PageSize(resultsperpage)
    • Description:
      • Sets the number of results returned each time AX:API_Search is called.
    • Parameters:
      • resultsperpage = the number of results you want per page.
    • Example:
      • AX:API_PageSize(10)

  • function AX:API_Search(cmd,param)
    • Description:
      • Initiates a search of the soundlib (i.e. /ax s keyword).
    • Parameters:
      • cmd = AX.s_CMD_SEARCH, AX.s_CMD_PGDN, AX.s_CMD_PGUP, AX.s_CMD_MATCH, AX.s_CMD_REFRESH or AX.s_CMD_BEGIN (i.e. respective /ax s, /ax d, /ax u, /ax m, /ax r, /ax b equivalents)
        • If cmd is AX.s_CMD_SEARCH, param defines the search keyword.
        • If cmd is AX.s_CMD_MATCH, param defines which search result to display first.
        • If cmd is AX.s_CMD_BEGIN, param defines which sound index to display results from.
      • param = Only relevant when cmd is AX.s_CMD_SEARCH, AX.s_CMD_MATCH or AX.s_CMD_BEGIN. Assign it "" the rest of the time.
        • if param starts with "#" the rest of keyword is assumed to be a sound index number, so AX:API_Search(anything,"#512") will return one result (i.e. same as /ax i 512)
    • Returns:
      • true if the search is carried out.
      • false if the search can not be carried out (i.e. searching out of bounds with next/prev).
    • Note:
      • AX.s_CMD_* variables (e.g. AX.s_CMD_SEARCH, AX.s_CMD_PGDN) are store the appropriate localized command for each action. As these may change between localized language, it is highly recommended that you use them. So instead of AX:API_Search("s","brew") use AX:API_Search(AX.s_CMD_SEARCH,"brew").
      • Results are effected by AUDIOX_CONFIG.interpret:-
        • If AUDIOX_CONFIG.interpret = true then search results contain matches for both the user entered keyword(s) and any pre-search translation(s) adjustments.
        • If AUDIOX_CONFIG.interpret = false then search results contain matches for the user entered keyword(s) only.
    • Examples:
      • success = AX:API_Search(AX.s_CMD_SEARCH,"brew") -- Start searching for "brew" (i.e. /ax s brew)
      • success = AX:API_Search(AX.s_CMD_PGDN,"") -- Get next page of results (i.e. /ax d)
      • success = AX:API_Search(AX.s_CMD_PGUP,"") -- Get prev page of results (i.e. /ax u)
      • success = AX:API_Search(AX.s_CMD_REFRESH,"") -- Refresh current page of results (i.e. /ax r)
      • success = AX:API_Search(AX.s_CMD_MATCH,"15") -- Get next page of results (i.e. /ax m 15)
      • success = AX:API_Search(AX.s_CMD_BEGIN,"3000") -- Get prev page of results (i.e. /ax b 3000)

  • function AX:API_LinkSlashCmd(soundpath)
    • Description:
      • Inserts soundpath into the ChatframeEditbox as /script PlaySoundFile(<soundpath>).
    • Parameters:
      • soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
      • soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1) E.g. 512
    • Notes:
      • Opens ChatFrameEditBox if it isn't already open.
      • Does not send the link. Add ChatEdit_SendText(ChatFrameEditBox,1) to your mod for that.
    • Examples:
      • AX:API_LinkSlashCmd("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
      • AX:API_LinkSlashCmd(512)

  • function AX:API_LinkSoundPath(soundpath)
    • Description:
      • Inserts soundpath into the ChatframeEditbox as an AudioX2 link (icon or text depending on user settings).
    • Parameters:
      • soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
      • soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1) E.g. 512
    • Notes:
      • Opens ChatFrameEditBox if it isn't already open.
      • Ensures output channel is valid.
      • Does not send the link. Add ChatEdit_SendText(ChatFrameEditBox,1) to your mod for that.
    • Examples:
      • AX:API_LinkSoundPath("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
      • AX:API_LinkSoundPath(512)

  • function AX:API_Play(sound,[music])
    • Description:
      • Plays a soundpath or index with double click prevention.
    • Parameters:
      • soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
      • soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1). E.g. 512
    • Optional Parameter:
      • music = true to play as background music using PlayMusic().
      • music = false to play as soundfx using PlaySoundFile().
      • music = nil (i.e. omitted) to allow AudioX to decide how to play sample.
    • Examples:
      • AX:API_Play("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
      • AX:API_Play(512)
      • AX:API_Play("Sound\\Music\\ZoneMusic\\TavernUndead\\RA_UndeadTavern1A.mp3",true)
      • AX:API_Play(512,false)

  • function AX:API_Quiet()
    • Description:
      • Stops all sound playback.
    • Example:
      • AX:API_Quiet()

  • function AX:API_ToggleFavSample(sound)
    • Description:
      • Adds/removes favourites from favourites table.
    • Parameters:
      • soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
      • soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1) E.g. 512
    • Returns:
      • false if the sound is removed from the favourites table.
      • true if the sound is added to the favourites table.
    • Examples:
      • AX:API_LinkSoundPath("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
      • AX:API_LinkSoundPath(512)

  • function AX:API_ToggleFavMode(bool)
    • Description:
      • Is used to specify whether AudioX is searching the SoundLib or AUDIOX_FAVS.
    • Parameters:
      • bool = true if you want to search AUDIOX_FAVS favourites table.
      • bool = false if you want to search the main SoundLib.
      • Any other value will toggle the value of bool between true and false.
    • Examples:
      • AX:API_ToggleFavMode(true) -- Search AUDIOX_FAVS
      • AX:API_ToggleFavMode(false) -- Search SoundLib
      • AX:API_ToggleFavMode("") -- Toggle true/false
    • Important:
      • Sets AX.searchmode to the variable name of the table in use. It is highly recommended that all references to "SoundLib" is changed to _G[AX.searchmode] in you AudioX plugins.

  • function AX:API_IsFav(sound)
    • Description:
      • Is used to determine if a sound is in the favourites table.
    • Parameters:
      • soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
      • soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1) E.g. 512
    • Returns:
      • If value is greater than 0 then sound is in AUDIOX_FAVS array. The positive return value indicates the location of sound in AUDIOX_FAVS.
      • If value is less than 0 then sound is not in AUDIOX_FAVS array. The negative return value * -1 can be used to establish where the sound sound be inserted into AUDIOX_FAVS. However, save youself the effort and AX:API_ToggleFavSample(sound) instead!
    • Examples:
      • AX:API_LinkSoundPath("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
      • AX:API_LinkSoundPath(512)

  • function AX:API_FilterPathAndExt(sound)
    • Description:
      • Removed the path and file extension from soundpath (or that associated with a given soundindex).
    • Parameters:
      • soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
      • soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1) E.g. 512
    • Returns:
      • The main part of the filename. E.g. BloodElfMaleHello02
    • Examples:
      • AX:API_FilterPathAndExt("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
      • AX:API_FilterPathAndExt(512)

  • function AX:API_IndexFromPath(soundpath,usingsoundlib)
    • Description:
      • Attempt to discover the index number of a given soundpath using a binary search.
    • Requires:
      • _G[AX.searchmode] should be sorted in ascending order.
    • Parameters:
      • soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
      • usingsoundlib = true --return values from the SoundLib only.
      • usingsoundlib = false --return value for the _G[AX.searchmode] (i.e. SoundLib or AUDIOX_FAVS).
    • Returns:
      • If soundpath is found then idx is returned as a positive value.
      • If soundpath is not found then idx is returned as a negative value. Unsigning this value points to correction insertion point for the soundpath if it were to be inserted into _G[AX.searchmode] array.
    • Example:
      Code:
      idx = AX:API_IndexFromPath("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav",true)
         if idx > 0 then
           -- found
         else
           -- not found
         end

  • function AX:API_LineOut(key,path)
    • IMPORTANT:
      • This function should be hooked in your AudioX plugin.
    • Description:
      • AudioX outputs to API_LineOut everytime a search match is found for the current page size (set with API_PageSize).
    • Parameters:
      • key = Sound index number.
      • path = Sound path name.
    • Example Hook:
      Code:
      local AX_API_LineOut_orig = AX.API_LineOut
        local function Example_LineOut(self,...)
          local key,path = ...
          if myaddon_active then -- If your mod is enabled
            -- your search results line output code starts here E.g.
            print(key,path)
            -- your search results line output code ends here
          else
            AX_API_LineOut_orig(self,key,path)
          end
        end
        AX.API_LineOut = Example_LineOut

  • function AX:API_PageFooter(first,last,total,search,tsearch)
    • IMPORTANT:
      • This function should be hooked in your AudioX plugin.
    • Description:
      • AudioX outputs to AX:API_PageFooter at the end of each page of results.
    • Parameters:
      • first = result number of the first result in the current page.
      • last = result number of the last result in the current page.
      • total = total number of search matches found in the SoundLib.
      • search = keyword search was for (useful for sanity checking).
      • tsearch = translated keyword (nil if AUDIOX_CONFIG.interpret is false)
    • Example Hook:
      Code:
      local AX_API_PageFooter_orig = AX.API_PageFooter
        local function Example_PageFooter(self,...)
          local first,last,total,search,tsearch = ...
          if myaddon_active then  -- If your mod is enabled
            -- your footer code starts here E.g.
            print(first,last,total,search,tsearch)
            -- your footer code ends here
          else
            AX_API_PageFooter_orig(self,first,last,total,search,tsearch)
          end
        end
        AX.API_PageFooter = Example_PageFooter

  • function AX:API_Notice(msg)
    • IMPORTANT:
      • This function should be hooked in your AudioX plugin.
    • Description:
      • AudioX outputs to AX:API_Notice whenever an error or verbose notice would be displayed.
    • Parameters:
      • msg = Error message text (less "AudioX> ")
    • Example Hook:
      Code:
      local AX_API_Notice_orig = AX.API_Notice
        local function Example_API_Notice(self,...)
          local msg = ...
          if myaddon_active then -- If your mod is enabled
            -- your search results line output code starts here E.g.
            print(msg)
            -- your search results line output code ends here
          else
            AX_API_Notice_orig(self,msg)
          end
        end
        AX.API_Notice = Example_Notice
 
Stats
Files: 1
Downloads: 4,450
Favorites: 62

Menu
» Home
» News Archive

» F.A.Q.
» Bug Reports
» Feature Request
» Interface List

New & Updated
» AudioX II


WOWInterface