-
-
Notifications
You must be signed in to change notification settings - Fork 7
API Utility functions
Utility functions
-
Functions
- Musician.Utils.Print
- Musician.Utils.Debug
- Musician.Utils.PrintError
- Musician.Utils.Error
- Musician.Utils.Popup
- Musician.Utils.Highlight
- Musician.Utils.RemoveHighlight
- Musician.Utils.GetColorCode
- Musician.Utils.FormatText
- Musician.Utils.GetLink
- Musician.Utils.RemoveLinks
- Musician.Utils.GetPlayerLink
- Musician.Utils.GetUrlLink
- Musician.Utils.GetFullPlayerName
- Musician.Utils.FormatPlayerName
- Musician.Utils.IsBattleNetID
- Musician.Utils.GetBattleNetAccountID
- Musician.Utils.GetBattleNetAccount
- Musician.Utils.GetBattleNetGameAccount
- Musician.Utils.GetBattleNetGameAccounts
- Musician.Utils.IsBattleNetGameAccountOnline
- Musician.Utils.GetChatIcon
- Musician.Utils.GetPlayerPosition
- Musician.Utils.DisplayEmote
- Musician.Utils.RemoveChatMessage
- Musician.Utils.PackNumber
- Musician.Utils.UnpackNumber
- Musician.Utils.PackTime
- Musician.Utils.UnpackTime
- Musician.Utils.PackPlayerGuid
- Musician.Utils.UnpackPlayerGuid
- Musician.Utils.PackPlayerPosition
- Musician.Utils.UnpackPlayerPosition
- Musician.Utils.FromHex
- Musician.Utils.ToHex
- Musician.Utils.SongIsPlaying
- Musician.Utils.MuteGameMusic
- Musician.Utils.SetInstrumentToysMuted
- Musician.Utils.GetMaxPolyphony
- Musician.Utils.GetSoundCacheSize
- Musician.Utils.GetCurrentAudioSettings
- Musician.Utils.GetNewAudioSettings
- Musician.Utils.UpdateAudioSettings
- Musician.Utils.AdjustAudioSettings
- Musician.Utils.GetNormalizedRealmName
- Musician.Utils.GetRealmLocale
- Musician.Utils.NormalizePlayerName
- Musician.Utils.NormalizeSongName
- Musician.Utils.SimplePlayerName
- Musician.Utils.PlayerRealm
- Musician.Utils.PlayerIsInGroup
- Musician.Utils.PlayerIsMyself
- Musician.Utils.PlayerIsOnSameRealm
- Musician.Utils.Ellipsis
- Musician.Utils.GetMsg
- Musician.Utils.GetPromoEmote
- Musician.Utils.HasPromoEmote
- Musician.Utils.ResetFullPromoEmoteCooldown
- Musician.Utils.OverrideNextFullPromoEmote
- Musician.Utils.SendPromoEmote
- Musician.Utils.GetVersionText
- Musician.Utils.VersionCompare
- Musician.Utils.PaddingZeros
- Musician.Utils.FormatTime
- Musician.Utils.ParseTime
- Musician.Utils.ShallowCopy
- Musician.Utils.DeepCopy
- Musician.Utils.DeepMerge
- Musician.Utils.FlipTable
- Musician.Utils.GetOs
- Musician.Utils.EasyMenu
- Musician.Utils.EasyMenu_Initialize
- Musician.Utils.SetFontStringTextFixedSize
- Musician.Utils.GetByteReader
- Musician.Utils.ForEach
- Musician.Utils.GetRandomArgument
- Musician.Utils.CheckModuleDependencies
Display a message in the console
Musician.Utils.Print(msg)Arguments
- msg (string)
Print debug stuff in the console
Musician.Utils.Debug(module, ...)Arguments
- module (string)
- ... (string)
Display an error message in the console
Musician.Utils.PrintError(msg)Arguments
- msg (string)
Display an error message in a popup
Musician.Utils.Error(msg)Arguments
- msg (string)
Display a message in a popup
Musician.Utils.Popup(msg, callback, force)Arguments
- msg (string)
- callback (function)
- force (boolean)
Highlight text
highlightedText = Musician.Utils.Highlight(text, color)Arguments
- text (string)
- color (string|Color)
Returns
- highlightedText (string)
Remove text coloring
text = Musician.Utils.RemoveHighlight(highlightedText)Arguments
- highlightedText (string)
Returns
- text (string)
Get color code from RGB values
colorCode = Musician.Utils.GetColorCode(r, g, b)Arguments
- r (number) 0-1
- g (number) 0-1
- b (number) 0-1
Returns
- colorCode (string)
Format text, adding highlights etc.
formattedText = Musician.Utils.FormatText(text)Arguments
- text (string)
Returns
- formattedText (string)
Get hyperlink
link = Musician.Utils.GetLink(command, text, ...)Arguments
- command (string)
- text (string)
- ... (string)
Returns
- link (string)
Remove hyperlinks from text
text = Musician.Utils.RemoveLinks(textWithLinks)Arguments
- textWithLinks (string)
Returns
- text (string)
Get player hyperlink
playerLink = Musician.Utils.GetPlayerLink(player)Arguments
- player (string)
Returns
- playerLink (string)
Get URL hyperlink
urlLink = Musician.Utils.GetUrlLink(url)Arguments
- url (string)
Returns
- urlLink (string)
Get player full name with realm slug or Battle.net account name if a Battle.net game account ID is provided.
fullPlayerName = Musician.Utils.GetFullPlayerName(playerOrGameAccountID)Arguments
- playerOrGameAccountID (string|number)
Returns
- fullPlayerName (string)
Get player name for display
formattedPlayerName = Musician.Utils.FormatPlayerName(player)Arguments
- player (string)
Returns
- formattedPlayerName (string)
Return true when the provided player name is a Battle.net account ID or Battle.net game account ID.
isBattleNetID = Musician.Utils.IsBattleNetID(playerName)Arguments
- playerName (string|number)
Returns
- isBattleNetID (boolean)
Get the Battle.net account ID from the Battle.net game account ID.
accountID = Musician.Utils.GetBattleNetAccountID(gameAccountID)Arguments
- gameAccountID (number)
Returns
- accountID (number)
Get Battle.net account info for provided Battle.net account ID.
accountInfo = Musician.Utils.GetBattleNetAccount(accountID)Arguments
- accountID (number)
Returns
- accountInfo (table)
Get Battle.net WoW game account info for provided Battle.net game account ID.
gameAccountInfo = Musician.Utils.GetBattleNetGameAccount(gameAccountID)Arguments
- gameAccountID (number)
Returns
- gameAccountInfo (table)
Get WoW game accounts info for provided Battle.net account ID.
gameAccountsInfo = Musician.Utils.GetBattleNetGameAccounts(accountID)Arguments
- accountID (number)
Returns
- gameAccountsInfo (table)
Indicates whenever the provided Battle.net game account ID is online
isOnline = Musician.Utils.IsBattleNetGameAccountOnline(gameAccountID)Arguments
- gameAccountID (number)
Returns
- isOnline (boolean)
Return the code to insert an icon in a chat message or a text string
chatIcon = Musician.Utils.GetChatIcon(path, r, g, b)Arguments
- path (string)
- r (number) 0-1 (default=0)
- g (number) 0-1 (default=0)
- b (number) 0-1 (default=0)
Returns
- chatIcon (string)
Get the player position in the 3D world
posY, posX, posZ, instanceID = Musician.Utils.GetPlayerPosition()Returns
- posY (number)
- posX (number)
- posZ (number) Always 0
- instanceID (number)
Display a faked emote
Musician.Utils.DisplayEmote(player, playerGUID, message)Arguments
- player (string)
- playerGUID (string)
- message (string)
Remove a chat message by its line ID
Musician.Utils.RemoveChatMessage(lineID)Arguments
- lineID (int)
Pack an integer number into a string
data = Musician.Utils.PackNumber(num, bytes)Arguments
- num (int) integer to pack
- bytes (int) number of bytes
Returns
- data (string)
Unpack a string into an integer number
num = Musician.Utils.UnpackNumber(data)Arguments
- data (string)
Returns
- num (int)
Pack a time or duration in seconds into a string
data = Musician.Utils.PackTime(seconds, bytes, fps)Arguments
- seconds (float)
- bytes (int) Number of bytes
- fps (float) Precision in frames par second
Returns
- data (string)
Unpack a string into a time or duration in seconds
seconds = Musician.Utils.UnpackTime(data, fps)Arguments
- data (string)
- fps (float) Precision in frames par second
Returns
- seconds (float)
Pack player GUID into a 6-byte string
data = Musician.Utils.PackPlayerGuid()Returns
- data (string)
Unpack player GUID from string
guid = Musician.Utils.UnpackPlayerGuid(str)Arguments
- str (string)
Returns
- guid (string)
Pack player position into a 18-byte chunk string
data = Musician.Utils.PackPlayerPosition()Returns
- data (string)
Unpack player position from chunk string
posY, posX, posZ, instanceID, guid = Musician.Utils.UnpackPlayerPosition(str)Arguments
- str (string)
Returns
- posY (number)
- posX (number)
- posZ (number)
- instanceID (int)
- guid (string)
Convert hex string to string
str = Musician.Utils.FromHex(hex)Arguments
- hex (string)
Returns
- str (string)
Convert string to hex string
hex = Musician.Utils.ToHex(str)Arguments
- str (string)
Returns
- hex (string)
Return true if a song is actually playing and is audible
isPlaying = Musician.Utils.SongIsPlaying()Returns
- isPlaying (boolean)
Start or stop the actual game music if a song can actually be heard
Musician.Utils.MuteGameMusic(force)Arguments
- force (boolean)
Mute or unmute music from instrument toys (Retail only)
Musician.Utils.SetInstrumentToysMuted(isMuted)Arguments
- isMuted (boolean)
Calculate the maximum polyphony depending on the enabled audio channels.
polyphony = Musician.Utils.GetMaxPolyphony()Returns
- polyphony (number)
Get the recommended total sound cache size.
cacheSize = Musician.Utils.GetSoundCacheSize()Returns
- cacheSize (number) in MB
Get the current audio settings.
audioSettings = Musician.Utils.GetCurrentAudioSettings()Returns
- audioSettings (table)
Get the new audio settings that differs from the provided ones.
newSettings = Musician.Utils.GetNewAudioSettings(oldSettings)Arguments
- oldSettings (table) as returned by Musician.Utils.GetCurrentAudioSettings()
Returns
- newSettings (table)
Update the audio settings to the new provided parameters
Musician.Utils.UpdateAudioSettings(newSettings, [noSoundSystemRestart=false])Arguments
- newSettings (table) as returned by Musician.Utils.GetCurrentAudioSettings() or Musician.Utils.GetNewAudioSettings()
- [noSoundSystemRestart=false] (boolean) Don't restart sound system when true
Automatically adjust the audio settings, if needed.
Musician.Utils.AdjustAudioSettings([noSoundSystemRestart=false])Arguments
- [noSoundSystemRestart=false] (boolean) Don't restart sound system when true
Return the normalized realm name the player belongs to
Safer than the standard GetNormalizedRealmName() that may return nil sometimes
realmName = Musician.Utils.GetNormalizedRealmName()Returns
- realmName (string)
Return the short locale code of the realm the player belongs to
locale = Musician.Utils.GetRealmLocale()Returns
- locale (string) 'en', 'fr' etc.
Return the normalized player name, including realm slug. Normalized player name is a number if a Battle.net account ID or Battle.net game account ID is provided.
normalizedPlayerName = Musician.Utils.NormalizePlayerName(playerName)Arguments
- playerName (string|number)
Returns
- normalizedPlayerName (string|number)
Return the normalized song name
normalizedSongName = Musician.Utils.NormalizeSongName(songName)Arguments
- songName (string)
Returns
- normalizedSongName (string)
Return the simple player name, including the realm slug if needed
simpleName = Musician.Utils.SimplePlayerName(playerName)Arguments
- playerName (string)
Returns
- simpleName (string)
Return the player realm slug
realmSlug = Musician.Utils.PlayerRealm(playerName)Arguments
- playerName (string)
Returns
- realmSlug (string)
Return true if the player is in my party or raid
isInMyGroup = Musician.Utils.PlayerIsInGroup(playerName)Arguments
- playerName (string)
Returns
- isInMyGroup (boolean)
Return true if the provided player name is myself
isMyself = Musician.Utils.PlayerIsMyself(playerName)Arguments
- playerName (string)
Returns
- isMyself (boolean)
Return true if the provided player name is on the same realm or connected realm as me
isOnSameRealm = Musician.Utils.PlayerIsOnSameRealm(playerName)Arguments
- playerName (string)
Returns
- isOnSameRealm (boolean)
Shortens the UTF-8 text with ellipsis if its size in bytes is longer than specified
ellipsisText = Musician.Utils.Ellipsis(text, maxBytes)Arguments
- text (string)
- maxBytes (int)
Returns
- ellipsisText (string)
Returns localized message
localizedMsg = Musician.Utils.GetMsg(msg, locale)Arguments
- msg (string)
- locale (string) Defaults to the realm locale (optional)
Returns
- localizedMsg (string)
Return the "Player is playing music" emote with promo message
promoEmote = Musician.Utils.GetPromoEmote()Returns
- promoEmote (string)
Return true if the message contains the promo emote, in any language
hasPromoEmote, isFullPromoEmote = Musician.Utils.HasPromoEmote(message)Arguments
- message (string)
Returns
- hasPromoEmote (boolean)
- isFullPromoEmote (boolean) true if the emote contains the part inviting other players to install Musician
Mark the full promo emote as recently seen
Musician.Utils.ResetFullPromoEmoteCooldown()Override the next full promo emote
Musician.Utils.OverrideNextFullPromoEmote()Send the "Player is playing music" emote with promo message
Musician.Utils.SendPromoEmote()Return the current version as text for the end user
version = Musician.Utils.GetVersionText()Returns
- version (string)
Compare two version numbers
difference = Musician.Utils.VersionCompare(versionA, versionB)Arguments
- versionA (string)
- versionB (string)
Returns
- difference (number) 0 if equal, positive value if A > B, negative value if A < B
Add padding zeros
formattedNumber = Musician.Utils.PaddingZeros(number, zeros)Arguments
- number (int)
- zeros (int)
Returns
- formattedNumber (string)
Format time to mm:ss.ss format
formattedTime = Musician.Utils.FormatTime(time, simple)Arguments
- time (number)
- simple (boolean)
Returns
- formattedTime (string)
Parse time in seconds from mm:ss.ss format
seconds = Musician.Utils.ParseTime(timestamp)Arguments
- timestamp (string)
Returns
- seconds (number)
Shallow copy a table
http://lua-users.org/wiki/CopyTable
copy = Musician.Utils.ShallowCopy(orig)Arguments
- orig (table)
Returns
- copy (table)
Deep copy a table
http://lua-users.org/wiki/CopyTable
copy = Musician.Utils.DeepCopy(orig)Arguments
- orig (table)
Returns
- copy (table)
Deep merge two tables
merged = Musician.Utils.DeepMerge(merged, orig)Arguments
- merged (table)
- orig (table)
Returns
- merged (table)
Flip a table
flipped = Musician.Utils.FlipTable(orig)Arguments
- orig (table)
Returns
- flipped (table)
Return operating system name
os = Musician.Utils.GetOs()Returns
- os (string)
Blizzard's EasyMenu using MSA_DropDownMenu
Musician.Utils.EasyMenu()Blizzard's EasyMenu_Initialize using MSA_DropDownMenu
Musician.Utils.EasyMenu_Initialize()Set text to a FontString element ensuring the visual text size is respected
Musician.Utils.SetFontStringTextFixedSize(fontString, text)Arguments
- fontString (FontString)
- text (string)
Return byte reader functions for provided data string
readBytes = Musician.Utils.GetByteReader(data, err)Arguments
- data (string)
- err (string) Error to be returned in case of reading error
Returns
- readBytes (function) , getCursor (function)
Call function for each item of the provided table
Musician.Utils.ForEach(list, func)Arguments
- list (table)
- func (function) Takes 3 arguments: value, key and the provided table.
Randomly returns one of the provided arguments
Musician.Utils.GetRandomArgument()Check third party add-on dependencies for a module. Return false and display an error message if the provided check function is not resolved.
@return isValid True if the dependencies are correct.
Musician.Utils.CheckModuleDependencies(moduleName, checkFunc)Arguments
- moduleName (string) Name of the module/add-on
- checkFunc (function) Returns false or throws an error if the dependencides don't match
Table of contents
- User guide (FR)
- Optional modules
- What the FAQ
- Tips and Tricks
- Music producer guide
- Localization
- Technical design
- API documentation
Discord / MusicianList / Patreon / Donate