LibFreeMedia is a small library to facilitate the sharing of media resources between different World of Warcraft addons. It was developed to provide a free software alternative to the proprietary LibSharedMedia.

Sharing media works best for both users as well as addon developers if everyone can access the shared media pool equally, and this includes authors that want to release their addons as free software. Therefore this library interoperates with LibShareMedia. Media registered using one library can be retrieved with the other and vice versa. See Interopability for the limitations of this interopability.

LibFreeMedia registers as a library using LibStub. Use LibStub to acquire a handle to the libary:

local lib = LibStub:GetLibrary("LibFreeMedia")

lib:Register(kind, identifier, data)

• kind (string): the kind of media you are registering. Some examples are "font", "background" or "statusbar"
• identifier (string): The (unique among its kind) name to identify the media. Users will often see this name, so use a descriptive name.
• data (any): The data that represents the media. After it is registered the library takes ownership of the data and it must not be changed.

The return value is a boolean indicating whether the media was registered successfully. Failure may happen for a number of reasons, including registering invalid data or the identifier already has registered media for that kind.

local libfm = LibStub:GetLibrary("LibFreeMedia")
libfm:Register("font", "Roboto Regular", "Interface\\AddOn\\MyAddon\\Fonts\\Roboto Regular.ttf")
libfm:Register("font", "Roboto Bold", "Interface\\AddOn\\MyAddon\\Fonts\\Roboto Bold.ttf")

if not libfm:Register("font", "Roboto Bold", "Interface\\AddOn\\MyAddon\\Fonts\\Roboto Bold.ttf") then
    error("The media registration failed")
end

lib:Get(kind, identifier)

• kind (string): the kind of media you want to retrieve. Some examples are "font", "background" or "statusbar".
• identifier (string): The name of the media you want to retrieve.

If the media exists, its data is returned. The type of this data depends on the kind of media. LibFreeMedia retains ownership of this data and you must not alter it in place.

If the media does not exist the function will return nil.

local libfm = LibStub:GetLibrary("LibFreeMedia")

local robotoRegular = libfm:Get("font", "Roboto Regular")
if robotoRegular then
    print("Successfully got the font location:", robotoRegular)
else
    print("The 'Roboto Regular' font could not be retrieved")
end

lib:GetList(kind)

• kind (string): the kind of media you want to get a list of. Some examples are "font", "background" or "statusbar".

If there is media registered for the requested kind it will be returned as a sorted sequence table of media identifiers for the requested kind. If there is no media of the requested kind then this function will return either nil or an empty table.

LibSharedMedia retains ownership of the returned tables and they should not be altered in place. These tables may be reused by LibSharedMedia and and media that is registered in the future could be added to these tables but this behavior should not be relied on. If you require an up to date list, call the library to receive one. If you require a snapshot to remain static, make a deep copy.

local libfm = LibStub:GetLibrary("LibFreeMedia")

local fonts = libfm:GetList("font")
if fonts == nil or #fonts == 0 then
    print("No registered fonts found")
else
    print("Registered fonts", table.concat(fonts, ", "))
end

lib:GetTable(kind)

• kind (string): the kind of media you want to get a list of. Some examples are "font", "background" or "statusbar".

If there is media registered for the requested kind it will be returned as a table with identifier:data pairs. If there is no media of the requested kind then this function will return either nil or an empty table.

LibSharedMedia retains ownership of the returned tables and they should not be altered in place. These tables may be reused by LibSharedMedia and and media that is registered in the future could be added to these tables but this behavior should not be relied on. If you require an up to date list, call the library to receive one. If you require a snapshot to remain static, make a deep copy.

local libfm = LibStub:GetLibrary("LibFreeMedia")

local fonts = libfm:GetTable("font") or {}

for identifier, data in pairs(fonts) do
    print(identifier, data)
end

The recommended way to include LibFreeMedia in your addon is embedding it and getting a handle using LibStub. To do this you To do this simply grab one of the embed archives from the releases and extract these files in your addon. Do the same with LibStub. This will get you a directory tree similar to the following:

YourAddon/libs/LibFreeMedia/LibFreeMedia.lua
YourAddon/libs/LibStub/LibStub.lua
YourAddon/YourAddon.toc
...

Simply add LibStub.lua and LibFreeMedia.lua as the first few files in your YourAddon.toc as follows:

## Interface: 100100
## Title: YourAddon
## Version: 4.20.69

# List LibStub and then LibFreeMedia
libs/LibStub/LibStub.lua
libs/LibStub/LibFreeMedia.lua

# List all your addon files as desired

Since it is in the interested of both users and developers to not create additional pools for shared media, LibFreeMedia attempts to interoperate seamlessly with LibSharedMedia. However, there is no 100% parity between LibFreeMedia and LibSharedMedia. This section will list all the areas where LibFreeMedia differs from LibSharedMedia.

LibFreeMedia does not support making callbacks on media registration. Any addon that relies on these callbacks in LibSharedMedia will currently not receive notifications when media is registered using LibFreeMedia. This is likely temporary, see issue #1.

LibFreeMedia does not support default return values for missing media, nor does it allow you to register a particular piece of media as the default for a specific kind.

LibFreeMedia does not support language masks for font registration. This is not likely to change.

LibFreeMedia does not attempt to be a drop-in replacement for LibSharedMedia. The API behaves slightly different. If there is demand for a drop-in replacement then this could change.