### Install Dependencies for Development

Source: https://github.com/music-encoding/sibmei/blob/develop/README.md

Install necessary dependencies for developing the Sibmei plugin using npm. Ensure git and node are installed beforehand.

```shell
git clone git@github.com:music-encoding/sibmei.git
cd sibmei
npm install
```

--------------------------------

### Build Plugin for Development

Source: https://github.com/music-encoding/sibmei/blob/develop/README.md

Start the compiler to build the plugin and watch for source file changes. Rebuilds occur automatically on save.

```shell
npm run develop
```

--------------------------------

### Example Sibmei Extension Plugin

Source: https://github.com/music-encoding/sibmei/blob/develop/Extensions.md

This is a basic example of a Sibmei extension plugin written in ManuScript. It demonstrates how to declare the API version, initialize the extension, and register text handlers for custom text styles.

```js
{
  //"The `SibmeiExtensionAPIVersion` field must be present so Sibmei can"
  //"recognize compatible extensions"
  SibmeiExtensionAPIVersion "3.0.0"

  Initialize "() {
    // The extension choice dialog will list this extension as
    // 'Example extension' (the first argument to to AddToPluginsMenu()).
    // Second argument can be `null` because an extension plugin does not need a
    // `Run()` method.
    AddToPluginsMenu('Example extension', null);
  }"

  //"InitSibmeiExtension() is the entry point for Sibmei and must be present"
  //"for Sibmei to recognize an extension plugin."
  InitSibmeiExtension "(api) { 
    // Declare which text styles this extension handles
    api.RegisterTextHandlers('StyleAsText', 'ControlEventTemplateHandler', CreateDictionary(
      // We want to add support for Text objects matching
      //   textObj.StyleAsText = 'My text'
      // Sibmei will append the generated element to the measure element.
      'My text', @Element('AnchoredText', null, api.FormattedText)
    ), Self);
  }"
}
```

--------------------------------

### XPath Test Example

Source: https://github.com/music-encoding/sibmei/blob/develop/README.md

Example of an XPath expression used for testing MEI export structures. Comments preceding the XPath are used in assertion messages.

```xquery
(: 
Clef is encoded in voices 1 and 2 of staff 1. Clef in layer 1 is the "main" clef,
clef in layer 2 has a @sameas attribute for pointing to the main clef.
:)
staff[@n=1][layer[@n=1]/clef][layer[@n=2]/clef[@sameas]]
```

--------------------------------

### Register Custom Symbol Handler in Sibmei

Source: https://context7.com/music-encoding/sibmei/llms.txt

Example of a complete custom handler method for symbols and how to register it with Sibmei. Requires the API object and the Sibelius bar object.

```js
// Complete custom handler example
function HandleMySymbol(api, obj) {
    // Option 1: Create from template
    symbolElement = api.GenerateControlEvent(obj, api.MeiFactory(api.template, obj));

    // Option 2: Create without template
    // symbolElement = api.GenerateControlEvent(obj, api.CreateElement('symbol'));
    // api.AddAttribute(symbolElement, 'fontfam', 'myCustomFont');
    // api.AddAttribute(symbolElement, 'glyph.name', 'mySymbolGlyph');

    // Add conditional logic based on object properties
    if (obj.ColorRed = 255) {
        api.AddAttribute(symbolElement, 'type', 'myRedType');
    }

    if (obj.Hidden) {
        api.AddAttribute(symbolElement, 'visible', 'false');
    }

    return symbolElement;
}

// Register the custom handler
InitSibmeiExtension "(api) {
    Self._property:MySymbolTemplate = @Element('dir', null,
        @Element('symbol', @Attrs(
            'fontfam', 'myCustomFont',
            'glyph.name', 'mySymbolGlyph'
        ))
    );

    api.RegisterSymbolHandlers('Name', 'HandleMySymbol', CreateDictionary(
        'My symbol', null
    ));
}"
```

--------------------------------

### Sibmei Extension API Methods

Source: https://github.com/music-encoding/sibmei/blob/develop/ExtensionApiMethods.md

These methods are exposed to extensions for interacting with Sibmei. Refer to the extension API documentation for usage examples.

```javascript
api.AddAttribute(element, attrname, attrval)
```

```javascript
api.AddChild(element, child)
```

```javascript
api.AddChildAtPosition(element, child, position)
```

```javascript
api.AppendToMeasure(element)
```

```javascript
api.CreateElement(tagname)
```

```javascript
api.GenerateControlEvent(bobj, element)
```

```javascript
api.GenerateModifier(bobj, element)
```

```javascript
api.GetAttribute(element, attrname)
```

```javascript
api.GetAttributes(element)
```

```javascript
api.GetChildren(element)
```

```javascript
api.GetElementById(id)
```

```javascript
api.GetId(element)
```

```javascript
api.GetName(element)
```

```javascript
api.GetTail(element)
```

```javascript
api.GetText(element)
```

```javascript
api.MeiFactory(data, bobj)
```

```javascript
api.RemoveAttribute(element, attrname)
```

```javascript
api.RemoveChild(element, child)
```

```javascript
api.SetId(element, newId)
```

```javascript
api.SetTail(element, val)
```

```javascript
api.SetText(element, val)
```

```javascript
api.XMLComment(comment)
```

--------------------------------

### Writing a Handler Method

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

This section explains how to write a custom Handler method when standard templates and handlers are insufficient. It provides examples of generating MEI elements and adding attributes based on object properties.

```APIDOC
## Writing a Handler Method

Where plain templates and the standard Sibmei handlers do not suffice, a dedicated Handler method can be written. Here is an example from an extension that outputs different markup, depending on what colour the handled object has.

```js
function HandleMySymbol (api, obj) {
    symbolElement = api.GenerateControlEvent(obj, api.MeiFactory(api.template, obj));
    if (obj.ColorRed = 255)
    {
        api.AddAttribute(symbolElement, 'type', 'myRedType');
    }
    return symbolElement;
} //$end
```

A Handler method receives the Handler object as first argument and the symbol, text, lyrics or line object as second argument. The Handler object exposes the extension API methods and objects (hence it's named `api` here) as well as the `template` field that can be passed to `api.MeiFactory()`.

A Handler method has to call `api.GenerateControlEvent()` or `api.GenerateModifier()`, otherwise the created MEI element will not be attached to the score.

While in the above example, the MEI element is generated from a registered template by calling `api.MeiFactory()`, a Handler method can however also create elements without relying on templates:

```js
function HandleMySymbol (api, obj) {
    symbolElement = api.GenerateControlEvent(api.Symbol());
    api.AddAttribute(symbolElement, 'fontfam', 'myCustomFont');
    api.AddAttribute(symbolElement, 'glyph.name', 'mySymbolGlyph');
    if (obj.ColorRed = 255)
    {
        api.AddAttribute(symbolElement, 'type', 'myRedType');
    }
    return symbolElement;
} //$end
```
```

--------------------------------

### Generate Control Event with MEI Factory

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

Example of generating an MEI element using `api.MeiFactory()` and attaching it to the score with `api.GenerateControlEvent()`. This pattern is common when working with templates.

```javascript
element = api.GenerateControlEvent(bobj, api.MeiFactory(template, bobj));
```

--------------------------------

### JavaScript: Template Action for Element Processing

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

This is an example of a Template Action function that processes an element template node. It creates a new MEI element, adds an attribute, and appends it to the parent.

```js
function SomeElementAction (self, parent, bobj) {
    element = api.MeiFactory(self.templateNode, bobj);
    api.AddAttribute(element, 'label', 'do something with the element');
    api.AddChild(parent, element);
} //$end
```

--------------------------------

### Registering Text Handlers

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

Example of using the `api.RegisterTextHandlers` function to register a handler for a specific text style. This function requires the property ID, the handler method name, and a dictionary mapping ID values to element templates.

```javascript
api.RegisterTextHandlers('StyleId', 'ControlEventTemplateHandler', CreateDictionary(
    'text.staff.technique', @Element('Dir', @Attrs('type', 'technique'),
        api.FormattedText
    )
));
```

--------------------------------

### Link Plugin for Development (Windows)

Source: https://github.com/music-encoding/sibmei/blob/develop/README.md

Create a symbolic link for the Sibelius plugin folder on Windows. This command must be run as administrator.

```batch
mklink /D "%APPDATA%\Avid\Sibelius\Plugins\MEI Export" "%HOMEPATH%\path\to\sibmei\build\develop"
```

--------------------------------

### Run Node Tests (Windows)

Source: https://github.com/music-encoding/sibmei/blob/develop/README.md

Batch script to run Node.js tests for Sibmei on Windows. It navigates to the project directory and executes 'npm test'.

```batch
x:
cd x:\path\to\sibmei
cmd /k npm test
```

--------------------------------

### Link Plugin for Development (Mac)

Source: https://github.com/music-encoding/sibmei/blob/develop/README.md

Create a symbolic link from the Sibelius plugin folder to the build folder for development on macOS. Adjust paths as necessary.

```shell
ln -s "~/path/to/sibmei/build/develop" "~/Library/Application Support/Avid/Sibelius 7.5/Plugins/MEI Export"
```

--------------------------------

### Run Node Tests (Mac)

Source: https://github.com/music-encoding/sibmei/blob/develop/README.md

Shell script to run Node.js tests for Sibmei on macOS. It navigates to the project directory and executes 'npm test'.

```shell
cd path/to/sibmei
npm test
```

--------------------------------

### Sibmei Template Placeholders Reference

Source: https://context7.com/music-encoding/sibmei/llms.txt

Demonstrates various placeholder types supported in Sibmei templates for dynamic MEI generation, including text, line endpoints, and lyrics.

```js
// Text placeholders
api.FormattedText   // Preserves bold, italic, and other formatting as <rend> elements
api.UnformattedText // Strips all formatting, outputs plain text
api.LyricText       // Special handling for lyrics (must be inside <syl>)

// Line endpoint placeholders (for @endid attribute values)
'PreciseMatch'  // Only set @endid if note/rest at exact EndPosition
'Next'          // Use closest following note/rest if no exact match
'Previous'      // Use closest preceding note/rest if no exact match
'Closest'       // Use closest note/rest in either direction

// Template examples with all placeholder types
textTemplate = @Element('dir', null, api.FormattedText);

lineTemplate = @Element('hairpin', @Attrs(
    'form', 'cres',
    'endid', 'Closest'
));

lyricTemplate = @Element('verse', null,
    @Element('syl', null, api.LyricText)
);
```

--------------------------------

### Dynamic Text Output

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

The placeholder is replaced by the text content from the data object, with formatting stripped for UnformattedText.

```xml
<persName><composer>Joseph Haydn</composer></persName>
```

--------------------------------

### Sibmei Extension API Methods

Source: https://github.com/music-encoding/sibmei/blob/develop/ExtensionApiMethods.md

A collection of methods provided by the Sibmei API for extensions to interact with music elements and data.

```APIDOC
## Sibmei Extension API

### Description
This section details the methods available for extensions to interact with the Sibmei music encoding system. These methods allow for manipulation of music elements, attributes, and the generation of specific data structures.

### Methods

- **AddAttribute(element, attrname, attrval)**: Adds an attribute to a given element.
- **AddChild(element, child)**: Adds a child element to a parent element.
- **AddChildAtPosition(element, child, position)**: Adds a child element to a parent element at a specific position.
- **AppendToMeasure(element)**: Appends an element to the current measure.
- **CreateElement(tagname)**: Creates a new element with the specified tag name.
- **GenerateControlEvent(bobj, element)**: Generates a control event.
- **GenerateModifier(bobj, element)**: Generates a modifier.
- **GetAttribute(element, attrname)**: Retrieves the value of a specified attribute from an element.
- **GetAttributes(element)**: Retrieves all attributes of an element.
- **GetChildren(element)**: Retrieves all child elements of a given element.
- **GetElementById(id)**: Retrieves an element by its ID.
- **GetId(element)**: Retrieves the ID of an element.
- **GetName(element)**: Retrieves the name of an element.
- **GetTail(element)**: Retrieves the tail value of an element.
- **GetText(element)**: Retrieves the text content of an element.
- **MeiFactory(data, bobj)**: Creates a new MEI object using the provided data and bobj.
- **RemoveAttribute(element, attrname)**: Removes an attribute from an element.
- **RemoveChild(element, child)**: Removes a child element from a parent element.
- **SetId(element, newId)**: Sets a new ID for an element.
- **SetTail(element, val)**: Sets the tail value for an element.
- **SetText(element, val)**: Sets the text content for an element.
- **XMLComment(comment)**: Creates an XML comment.

### Usage Notes
Refer to the [extension API documentation](Extensions.md) for detailed usage examples and further information.
```

--------------------------------

### Run MEI Export

Source: https://context7.com/music-encoding/sibmei/llms.txt

Initiates the MEI export process for the active Sibelius score. It validates the Sibelius version, prompts for a filename, processes musical elements, and writes the MEI XML output. Requires Sibelius 7 or higher.

```js
// Main entry point - called when user runs the plugin from Sibelius menu
function Run() {
    if (not InitGlobals(null)) {
        return null;
    }
    InitWarningsTracker();
    error = DoExport(Sibelius.ActiveScore, null);

    if (null != error) {
        InformAboutResults(error, false);
    } else {
        InformAboutResults('Done', false);
    }
}

// Core export function - can be called programmatically with specific filename
function DoExport(score, filename) {
    // Requires Sibelius 7 or higher
    if (Sibelius.ProgramVersion < 7000) {
        return _VersionNotSupported;
    }

    if (null = filename) {
        filename = GetExportFileName(score);
    }

    ResetXml();
    SetGlobalsForScore(score);
    ProcessScore();

    doc = GetDocument();
    export_status = MeiDocumentToFile(doc, filename);

    return null; // Success
}
```

--------------------------------

### XML Element Creation and Manipulation

Source: https://context7.com/music-encoding/sibmei/llms.txt

API methods for creating, adding attributes, setting text content, adding/removing children, and managing element IDs. Use these for direct XML manipulation within extension handlers.

```js
// Create a new element
element = api.CreateElement('dir');

// Add/get/remove attributes
api.AddAttribute(element, 'type', 'tempo');
api.AddAttribute(element, 'place', 'above');
value = api.GetAttribute(element, 'type');  // Returns 'tempo'
api.RemoveAttribute(element, 'place');

// Set/get text content
api.SetText(element, 'Allegro');
text = api.GetText(element);  // Returns 'Allegro'

// Set/get tail text (text after closing tag)
api.SetTail(element, ' ');
tail = api.GetTail(element);

// Add child elements
childElement = api.CreateElement('rend');
api.AddChild(element, childElement);
api.AddChildAtPosition(element, anotherChild, 0);  // Insert at position

// Get children and navigate
children = api.GetChildren(element);
elementName = api.GetName(element);  // Returns 'dir'

// Get element ID and lookup
id = api.GetId(element);
api.SetId(element, 'custom-id-123');
foundElement = api.GetElementById('custom-id-123');

// Remove child element
api.RemoveChild(element, childElement);

// Create XML comment
comment = api.XMLComment('This is a comment');
// Output: <!-- This is a comment -->
```

--------------------------------

### Register Lyric Handlers for Custom Styles

Source: https://context7.com/music-encoding/sibmei/llms.txt

Registers handlers for lyric items. Templates must include a '<syl>' element with 'api.LyricText' as a descendant. Sibmei automatically handles '@wordpos' and '@con' attributes.

```javascript
// Register lyrics handlers for custom lyric styles
api.RegisterLyricHandlers('StyleAsText', 'LyricTemplateHandler', CreateDictionary(
    'My italic lyrics', @Element('verse', null,
        @Element('syl', null,
            @Element('rend', @Attrs('rend', 'italic'), api.LyricText)
        )
    ),
    'Chorus lyrics', @Element('verse', @Attrs('label', 'chorus'),
        @Element('syl', null, api.LyricText)
    )
));
```

--------------------------------

### Sibmei Extension Plugin Structure

Source: https://context7.com/music-encoding/sibmei/llms.txt

Defines the structure for Sibmei extension plugins, including API version compatibility and the required `InitSibmeiExtension` method. This method is used to register custom handlers for text styles, symbols, lines, and lyrics.

```js
{
  // Required: Semantic version for API compatibility checking
  SibmeiExtensionAPIVersion "3.0.0"

  Initialize "() {
    AddToPluginsMenu('My Extension', null);
  }"

  // Required: Entry point called by Sibmei
  InitSibmeiExtension "(api) {
    // Register handlers for custom text styles
    api.RegisterTextHandlers('StyleAsText', 'ControlEventTemplateHandler', CreateDictionary(
      'My text', @Element('dir', null, @Element('anchoredText', null, api.FormattedText))
    ));

    // Register handlers for custom symbols
    api.RegisterSymbolHandlers('Name', 'ModifierTemplateHandler', CreateDictionary(
      'My symbol', @Element('artic', @Attrs('artic', 'acc'))
    ));

    // Register handlers for custom lines
    api.RegisterLineHandlers('StyleAsText', 'ControlEventTemplateHandler', CreateDictionary(
      'My line', @Element('line', @Attrs('type', 'myline', 'endid', 'PreciseMatch'))
    ));

    // Register handlers for custom lyrics styles
    api.RegisterLyricHandlers('StyleAsText', 'LyricTemplateHandler', CreateDictionary(
      'My lyrics', @Element('verse', null,
        @Element('syl', null,
          @Element('rend', @Attrs('rend', 'italic'), api.LyricText)
        )
      )
    ));
  }"
}
```

--------------------------------

### API Methods for Handlers

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

Details the core API methods available within a Handler object for generating and manipulating MEI elements.

```APIDOC
## API Methods for Handlers

A Handler method can use the following methods:

### `api.GenerateControlEvent()`

Takes two arguments:

* `bobj`: A `BarObject`
* `element`: An element that is created e.g. with `CreateElement()` or `MeiFactory()`.

`GenerateControlEvent()` takes care of adding the element to the `<measures>` and adds the following control event attributes:

* `@startid` (if a start object could be identified) and `@tstamp`. The addition of `@tstamp` can be suppressed by setting `@tstamp` to `' '` (e.g. in the template).

* If applicable (e.g. for lines), `@endid` (if an end object could be identified) and `@tstamp2`

* `@staff` and `@layer` (if object is staff-attached)

* For lines:

  * `@dur.ppq` (unless `Duration` is 0)
  * `@startho`, `@startvo`, `@endho`, `@endvo`

* For elements other than lines:

  * `@ho`, `@vo`

`GenerateControlEvent()` returns `element`, which allow patterns like:

```js
element = api.GenerateControlEvent(bobj, api.MeiFactory(template, bobj));
```

### `api.GenerateModifier()`

Works in the same way as `GenerateControlEvent()`, but attaches the element to `<note>`, `<chord>` or `<rest>` (depending on what's found at the position in the object's voice). Unlike `GenerateControlEvent()`, it does not add any attributes automatically.

### `api.MeiFactory()`

Takes two arguments:

* A [template](#registering-a-template)
* The text, line or symbol object for which an element is generated by means of the template. This parameter is only of importance if [dynamic template fields](#dynamic-template-fields) are used.

### `api.AddFormattedText()`

Takes two arguments:

* `parentElement`: MEI element that the formatted text nodes should be appended to.
* `textObj`: A `Text` or `SystemTextItem` object. Its `TextWithFormatting` property is converted to MEI markup.
```

--------------------------------

### Dynamic Text Placeholder

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

Use api.UnformattedText or api.FormattedText within templates to dynamically insert text content from data objects.

```javascript
@Element('PersName', null,
    @Element('Composer', null,
        api.UnformattedText
    )
)
```

--------------------------------

### api.MeiFactory() - MEI Element Generation

Source: https://context7.com/music-encoding/sibmei/llms.txt

Generates an MEI element from a declarative template. Templates define element structure using nested arrays with tag names, attributes, and child content. Supports dynamic placeholders.

```APIDOC
## api.MeiFactory()

### Description
Generates an MEI element from a declarative template. Templates describe element structure using nested arrays with tag names, attributes, and child content.

### Method
`api.MeiFactory(template, textObj)`

### Parameters
- **template** (object) - The declarative template defining the MEI element structure.
- **textObj** (object) - An object containing text content, potentially used for placeholders.

### Request Example
```js
// Template structure: @Element(tagName, @Attrs(...), children...)
template = @Element('p', null,
    'This is ',
    @Element('rend', @Attrs('rend', 'italic'),
        'declarative'
    ),
    ' MEI generation.'
);

// Generate element from template
element = api.MeiFactory(template, textObj);
// Output: <p>This is <rend rend='italic'>declarative</rend> MEI generation.</p>

// Using dynamic placeholders in templates
templateWithPlaceholders = @Element('persName', null,
    @Element('composer', null,
        api.UnformattedText  // Replaced with text object's content
    )
);
// For textObj.Text = 'Joseph Haydn':
// Output: <persName><composer>Joseph Haydn</composer></persName>
```
```

--------------------------------

### Custom Schema Location Configuration

Source: https://context7.com/music-encoding/sibmei/llms.txt

Configuration options for extensions to specify a custom MEI schema location or disable schema processing instructions entirely.

```APIDOC
## Custom Schema Location

### Description
Extensions can specify a custom MEI schema location or disable schema processing instructions entirely.

### Configuration Options

- **`CustomSchemaLocation "<URL>"`**: Specifies a URL for a custom MEI schema (e.g., `https://example.com/custom-mei-schema.rng`).
- **`CustomSchemaLocation "noSchema"`**: Disables schema processing instructions.

### Initialization

- **`Initialize "() { ... }"`**: A block for initialization code, often used to register plugins.
- **`InitSibmeiExtension "(api) { ... }"`**: A block for initializing the Sibmei extension, typically used to register handlers.

### Configuration Example
```json
{
  SibmeiExtensionAPIVersion "3.0.0"

  // Option 1: Specify custom schema URL
  CustomSchemaLocation "https://example.com/custom-mei-schema.rng"

  // Option 2: Disable schema processing instructions
  // CustomSchemaLocation "noSchema"

  Initialize "() {
    AddToPluginsMenu('Custom Schema Extension', null);
  }"

  InitSibmeiExtension "(api) {
    // Register handlers as needed
  }"
}
```
```

--------------------------------

### Generate MEI Element Without Templates

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

Create MEI elements directly using `api.Symbol()` and add custom attributes. This method is useful when a predefined template is not suitable. Remember to call `api.GenerateControlEvent()` to ensure the element is attached.

```javascript
function HandleMySymbol (api, obj) {
    symbolElement = api.GenerateControlEvent(api.Symbol());
    api.AddAttribute(symbolElement, 'fontfam', 'myCustomFont');
    api.AddAttribute(symbolElement, 'glyph.name', 'mySymbolGlyph');
    if (obj.ColorRed = 255)
    {
        api.AddAttribute(symbolElement, 'type', 'myRedType');
    }
    return symbolElement;
} //$end
```

--------------------------------

### Internal Handler Mapping Dictionaries

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

Pseudo-code illustrating the internal mapping dictionaries (`LineHandlers`, `TextHandlers`, `SymbolHandlers`) used to associate objects with their respective handlers based on style properties like `StyleId`, `StyleAsText`, `Index`, or `Name`.

```javascript
{
  StyleId: {
    'line.staff.slur.down': {
      HandleObject: function ControlEventTemplateHandler(this, bobj){...},
      template: ['Slur', {endid: 'PreciseMatch'}],
    }
  },
  StyleAsText: {
    // A line style that is handled with a custom, non-template based
    // handler method:
    'My Line': {
      HandleObject: function HandleMyLine(this, bobj){...},
      template: null,
    },
    // And another one that uses a template:
    'My template based line': {
      HandleObject: function ControlEventTemplateHandler(this, bobj){...},
      template: ['Line', {type: 'My other line'}],
    },
  },
}

```

--------------------------------

### Batch Export Sibelius Files to MEI

Source: https://context7.com/music-encoding/sibmei/llms.txt

Converts multiple Sibelius files to MEI format in a single operation. This function can also utilize optional extension plugins for customized exports. It sorts files before processing and reports any files that could not be opened.

```js
// Export multiple files with optional extension plugins
function ExportBatch(files, extensions, showFinalMessage) {
    if (not InitGlobals(extensions)) {
        return null;
    }
    InitWarningsTracker();

    utils.SortArray(files, false);
    numFiles = files.Length;
    exportCount = 0;

    for index = 0 to numFiles {
        file = Sibelius.GetFile(files[index]);
        score = GetScore(file);

        if (null = score) {
            RegisterWarning(null, 'File could not be opened', '');
        } else {
            error = DoExport(score, file.Name & '.mei');
            Sibelius.CloseWindow(False);

            if (null = error) {
                exportCount = exportCount + 1;
            }
        }
    }

    return true;
}
```

--------------------------------

### Generate Control Event with Template

Source: https://context7.com/music-encoding/sibmei/llms.txt

Creates a measure-attached control event element using a template. Automatically adds '@startid', '@tstamp', '@staff', '@layer', and positioning attributes.

```javascript
// Using GenerateControlEvent in a custom handler
function HandleMySymbol(api, obj) {
    // Create element from template
    symbolElement = api.GenerateControlEvent(obj, api.MeiFactory(api.template, obj));

    // Add conditional attributes based on object properties
    if (obj.ColorRed = 255) {
        api.AddAttribute(symbolElement, 'type', 'myRedType');
    }

    return symbolElement;
}
```

--------------------------------

### Convert Template to MEI

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

The api.MeiFactory or template Handler converts ManuScript templates into MEI XML.

```xml
<p>This is <rend rend='italic'>declarative</rend> MEI generation.</p>
```

--------------------------------

### api.AddFormattedText() - Formatted Text Conversion

Source: https://context7.com/music-encoding/sibmei/llms.txt

Converts a Sibelius text object's formatted content (bold, italic, etc.) into MEI markup and appends it as child elements to a specified parent element.

```APIDOC
## api.AddFormattedText()

### Description
Converts a Sibelius text object's formatted content (bold, italic, etc.) to MEI markup and appends it to a parent element.

### Method
`api.AddFormattedText(parentElement, textObj)`

### Parameters
- **parentElement** (object) - The MEI element to which the formatted text will be appended.
- **textObj** (object) - The Sibelius text object containing formatted content.

### Request Example
```js
// Add formatted text from a text object to an element
function HandleFormattedDirective(api, textObj) {
    dir = api.GenerateControlEvent(textObj, api.CreateElement('dir'));

    // TextWithFormatting contains text with inline formatting codes
    // AddFormattedText converts these to MEI <rend> elements
    api.AddFormattedText(dir, textObj);

    return dir;
}
// Input text: "Play **boldly** and _expressively_"
// Output: <dir>Play <rend rend="bold">boldly</rend> and <rend rend="italic">expressively</rend></dir>
```
```

--------------------------------

### Configure Custom MEI Schema Location

Source: https://context7.com/music-encoding/sibmei/llms.txt

Extensions can specify a custom MEI schema URL or disable schema processing instructions by setting CustomSchemaLocation. This allows for validation against specific schema definitions.

```json
{
  SibmeiExtensionAPIVersion "3.0.0"

  // Option 1: Specify custom schema URL
  CustomSchemaLocation "https://example.com/custom-mei-schema.rng"

  // Option 2: Disable schema processing instructions
  // CustomSchemaLocation "noSchema"

  Initialize "() {
    AddToPluginsMenu('Custom Schema Extension', null);
  }"

  InitSibmeiExtension "(api) {
    // Register handlers as needed
  }"
}
```

--------------------------------

### Register Symbol Handler with Custom Method

Source: https://context7.com/music-encoding/sibmei/llms.txt

Registers a symbol handler using a custom method name. A null template indicates that the handler method will manage element creation.

```javascript
// Register symbol with custom handler method
api.RegisterSymbolHandlers('Name', 'HandleMySymbol', CreateDictionary(
    'My symbol', null  // null template when using custom handler
));
```

--------------------------------

### XML Element Manipulation API

Source: https://context7.com/music-encoding/sibmei/llms.txt

Provides methods for creating and manipulating MEI XML elements within extension handlers, including attribute management, text content, child elements, and element identification.

```APIDOC
## XML Element Manipulation API

### Description
Methods for creating and manipulating MEI XML elements within extension handlers.

### Methods

- **`api.CreateElement(tagName)`**: Creates a new XML element.
- **`api.AddAttribute(element, name, value)`**: Adds or updates an attribute on an element.
- **`api.GetAttribute(element, name)`**: Retrieves the value of an attribute.
- **`api.RemoveAttribute(element, name)`**: Removes an attribute from an element.
- **`api.SetText(element, text)`**: Sets the text content of an element.
- **`api.GetText(element)`**: Retrieves the text content of an element.
- **`api.SetTail(element, text)`**: Sets the tail text (text after the closing tag) of an element.
- **`api.GetTail(element)`**: Retrieves the tail text of an element.
- **`api.AddChild(element, childElement)`**: Appends a child element to the end of the children list.
- **`api.AddChildAtPosition(element, childElement, position)`**: Inserts a child element at a specific position.
- **`api.GetChildren(element)`**: Retrieves a list of child elements.
- **`api.GetName(element)`**: Returns the tag name of the element.
- **`api.GetId(element)`**: Retrieves the ID of the element.
- **`api.SetId(element, id)`**: Sets the ID of the element.
- **`api.GetElementById(id)`**: Finds and returns an element by its ID.
- **`api.RemoveChild(element, childElement)`**: Removes a specific child element.
- **`api.XMLComment(text)`**: Creates an XML comment node.

### Request Example
```js
// Create a new element
element = api.CreateElement('dir');

// Add/get/remove attributes
api.AddAttribute(element, 'type', 'tempo');
api.AddAttribute(element, 'place', 'above');
value = api.GetAttribute(element, 'type');  // Returns 'tempo'
api.RemoveAttribute(element, 'place');

// Set/get text content
api.SetText(element, 'Allegro');
text = api.GetText(element);  // Returns 'Allegro'

// Set/get tail text (text after closing tag)
api.SetTail(element, ' ');
tail = api.GetTail(element);

// Add child elements
childElement = api.CreateElement('rend');
api.AddChild(element, childElement);
api.AddChildAtPosition(element, anotherChild, 0);  // Insert at position

// Get children and navigate
children = api.GetChildren(element);
elementName = api.GetName(element);  // Returns 'dir'

// Get element ID and lookup
id = api.GetId(element);
api.SetId(element, 'custom-id-123');
foundElement = api.GetElementById('custom-id-123');

// Remove child element
api.RemoveChild(element, childElement);

// Create XML comment
comment = api.XMLComment('This is a comment');
// Output: <!-- This is a comment -->
```
```

--------------------------------

### Generate MEI Element from Template

Source: https://context7.com/music-encoding/sibmei/llms.txt

Use api.MeiFactory to create MEI elements from declarative templates. Templates can include nested arrays for structure, attributes, and child content, supporting dynamic placeholders.

```js
// Template structure: @Element(tagName, @Attrs(...), children...)
template = @Element('p', null,
    'This is ',
    @Element('rend', @Attrs('rend', 'italic'),
        'declarative'
    ),
    ' MEI generation.'
);

// Generate element from template
element = api.MeiFactory(template, textObj);
// Output: <p>This is <rend rend='italic'>declarative</rend> MEI generation.</p>

// Using dynamic placeholders in templates
templateWithPlaceholders = @Element('persName', null,
    @Element('composer', null,
        api.UnformattedText  // Replaced with text object's content
    )
);
// For textObj.Text = 'Joseph Haydn':
// Output: <persName><composer>Joseph Haydn</composer></persName>
```

--------------------------------

### Generate MEI Element with Custom Attributes

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

Use this handler to generate an MEI element from a template and add custom attributes based on object properties. Ensure `api.GenerateControlEvent()` is called to attach the element to the score.

```javascript
function HandleMySymbol (api, obj) {
    symbolElement = api.GenerateControlEvent(obj, api.MeiFactory(api.template, obj));
    if (obj.ColorRed = 255)
    {
        api.AddAttribute(symbolElement, 'type', 'myRedType');
    }
    return symbolElement;
} //$end
```

--------------------------------

### Register Text Handlers by StyleId

Source: https://context7.com/music-encoding/sibmei/llms.txt

Registers handlers for text objects using their StyleId. This is typically used for built-in text styles.

```javascript
// Register text handlers using StyleId (for built-in styles)
api.RegisterTextHandlers('StyleId', 'ControlEventTemplateHandler', CreateDictionary(
    'text.staff.technique', @Element('Dir', @Attrs('type', 'technique'),
        api.FormattedText
    )
));
```

--------------------------------

### Register Symbol Handlers by Name

Source: https://context7.com/music-encoding/sibmei/llms.txt

Registers handlers for user-defined symbol objects using their Name. This allows for custom symbol behavior and representation.

```javascript
// Register symbol handlers using Name (for user-defined symbols)
api.RegisterSymbolHandlers('Name', 'ModifierTemplateHandler', CreateDictionary(
    'My soft accent', @Element('artic', @Attrs(
        'artic', 'acc',
        'glyph.auth', 'smufl',
        'glyph.name', 'articSoftAccentAbove',
        'glyph.num', 'U+ED40'
    ))
));
```

--------------------------------

### Register Text Handlers by StyleAsText

Source: https://context7.com/music-encoding/sibmei/llms.txt

Registers handlers for text objects using their StyleAsText property. This is used for user-defined text styles.

```javascript
// Register text handlers using StyleAsText (for user-defined styles)
api.RegisterTextHandlers('StyleAsText', 'ControlEventTemplateHandler', CreateDictionary(
    'My custom text', @Element('dir', null,
        @Element('anchoredText', @Attrs(), api.FormattedText)
    ),
    'Plain direction', @Element('dir', @Attrs(), api.UnformattedText)
));
```

--------------------------------

### RegisterLyricHandlers API

Source: https://context7.com/music-encoding/sibmei/llms.txt

Registers handlers for lyric items, ensuring templates include a `<syl>` element with `api.LyricText`.

```APIDOC
## api.RegisterLyricHandlers()

### Description
Registers handlers for lyric items. Templates must include a `<syl>` element with `api.LyricText` as a descendant. Sibmei automatically handles `@wordpos` and `@con` attributes.

### Method
`api.RegisterLyricHandlers(identifierType, handlerName, dictionary)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **identifierType** (string) - Required - Specifies whether to use 'StyleId' or 'StyleAsText'.
- **handlerName** (string) - Required - The name of the handler to use (e.g., 'LyricTemplateHandler').
- **dictionary** (object) - Required - A dictionary mapping lyric styles to MEI element structures.

### Request Example
```js
// Register lyrics handlers for custom lyric styles
api.RegisterLyricHandlers('StyleAsText', 'LyricTemplateHandler', CreateDictionary(
    'My italic lyrics', @Element('verse', null,
        @Element('syl', null,
            @Element('rend', @Attrs('rend', 'italic'), api.LyricText)
        )
    ),
    'Chorus lyrics', @Element('verse', @Attrs('label', 'chorus'),
        @Element('syl', null, api.LyricText)
    )
));
```

### Response
None (This function modifies internal handler registrations).
```

--------------------------------

### Handler Object Structure

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

A JavaScript-like pseudo-code representation of a handler object, consisting of a `HandleObject` method and a `template` field. This structure is used to manage different styles and symbols.

```javascript
{
    HandleObject: function ControlEventTemplateHandler(this, bobj){...},
    template: ['Slur', {endid: 'PreciseMatch'}],
}
```

--------------------------------

### Add Formatted Text to MEI Element

Source: https://context7.com/music-encoding/sibmei/llms.txt

Converts Sibelius text objects with formatting (bold, italic) into MEI markup using <rend> elements. This function is useful for translating rich text content into structured MEI.

```js
// Add formatted text from a text object to an element
function HandleFormattedDirective(api, textObj) {
    dir = api.GenerateControlEvent(textObj, api.CreateElement('dir'));

    // TextWithFormatting contains text with inline formatting codes
    // AddFormattedText converts these to MEI <rend> elements
    api.AddFormattedText(dir, textObj);

    return dir;
}
// Input text: "Play **boldly** and _expressively_"
// Output: <dir>Play <rend rend="bold">boldly</rend> and <rend rend="italic">expressively</rend></dir>
```

--------------------------------

### Define MEI Element with @Element

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

Use @Element to declaratively describe an MEI element with nested elements and attributes. @Attrs creates attribute dictionaries.

```javascript
@Element('P', null,
    'This is ',
    @Element('Rend', @Attrs('rend', 'italic'),
        'declarative'
    ),
    ' MEI generation.'
)
```

--------------------------------

### GenerateControlEvent API

Source: https://context7.com/music-encoding/sibmei/llms.txt

Creates a measure-attached control event element with automatic attribute generation.

```APIDOC
## api.GenerateControlEvent()

### Description
Creates a measure-attached control event element. Automatically adds `@startid`, `@tstamp`, `@staff`, `@layer`, and positioning attributes.

### Method
`api.GenerateControlEvent(obj, element)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **obj** (object) - Required - The source object containing data for the event.
- **element** (MEIElement) - Required - The MEI element to be generated or modified.

### Request Example
```js
// Using GenerateControlEvent in a custom handler
function HandleMySymbol(api, obj) {
    // Create element from template
    symbolElement = api.GenerateControlEvent(obj, api.MeiFactory(api.template, obj));

    // Add conditional attributes based on object properties
    if (obj.ColorRed = 255) {
        api.AddAttribute(symbolElement, 'type', 'myRedType');
    }

    return symbolElement;
}

// Creating control event without template
function HandleCustomDynamic(api, obj) {
    dynamElement = api.GenerateControlEvent(obj, api.CreateElement('dynam'));
    api.SetText(dynamElement, obj.Text);
    api.AddAttribute(dynamElement, 'place', 'below');
    return dynamElement;
}
```

### Response
- **MEIElement** - The generated control event element.
```

--------------------------------

### Generate Control Event without Template

Source: https://context7.com/music-encoding/sibmei/llms.txt

Creates a measure-attached control event element without a predefined template. This allows for dynamic element creation with specified attributes and text.

```javascript
// Creating control event without template
function HandleCustomDynamic(api, obj) {
    dynamElement = api.GenerateControlEvent(obj, api.CreateElement('dynam'));
    api.SetText(dynamElement, obj.Text);
    api.AddAttribute(dynamElement, 'place', 'below');
    return dynamElement;
}
```

--------------------------------

### GenerateModifier API

Source: https://context7.com/music-encoding/sibmei/llms.txt

Creates an element attached to the nearest note, chord, or rest at the object's position.

```APIDOC
## api.GenerateModifier()

### Description
Creates an element attached to the nearest `<note>`, `<chord>`, or `<rest>` at the object's position. Does not add automatic attributes like `GenerateControlEvent()`.

### Method
`api.GenerateModifier(obj, element)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **obj** (object) - Required - The source object containing data for the modifier.
- **element** (MEIElement) - Required - The MEI element to be generated or modified.

### Request Example
```js
// Using GenerateModifier for note-attached elements
function HandleMyArticulation(api, obj) {
    articElement = api.GenerateModifier(obj, api.MeiFactory(api.template, obj));

    // Modifiers are automatically attached to the closest note/chord/rest
    return articElement;
}

// Create articulation without template
function HandleCustomArticulation(api, obj) {
    artic = api.CreateElement('artic');
    api.AddAttribute(artic, 'artic', 'stacc');
    api.GenerateModifier(obj, artic);
    return artic;
}
```

### Response
- **MEIElement** - The generated modifier element.
```

--------------------------------

### Generate Modifier without Template

Source: https://context7.com/music-encoding/sibmei/llms.txt

Creates an element attached to the nearest note, chord, or rest without using a template. This allows for custom element creation with specific attributes.

```javascript
// Create articulation without template
function HandleCustomArticulation(api, obj) {
    artic = api.CreateElement('artic');
    api.AddAttribute(artic, 'artic', 'stacc');
    api.GenerateModifier(obj, artic);
    return artic;
}
```

--------------------------------

### Generate Modifier for Note-Attached Elements

Source: https://context7.com/music-encoding/sibmei/llms.txt

Creates an element attached to the nearest note, chord, or rest using a template. This function does not add automatic attributes like GenerateControlEvent.

```javascript
// Using GenerateModifier for note-attached elements
function HandleMyArticulation(api, obj) {
    articElement = api.GenerateModifier(obj, api.MeiFactory(api.template, obj));

    // Modifiers are automatically attached to the closest note/chord/rest
    return articElement;
}
```

--------------------------------

### api.AppendToMeasure() - Appending to Measure

Source: https://context7.com/music-encoding/sibmei/llms.txt

Directly appends an element to the current measure without adding control event attributes. This is useful for non-standard measure-attached content.

```APIDOC
## api.AppendToMeasure()

### Description
Directly appends an element to the current measure without adding control event attributes. Useful for non-standard measure-attached content.

### Method
`api.AppendToMeasure(element)`

### Parameters
- **element** (object) - The MEI element to append to the current measure.

### Returns
- The appended element.

### Request Example
```js
// Append element directly to measure without control event attributes
function HandleXPathAnnotation(api, textObj) {
    // Create annotation element
    annotElement = api.AppendToMeasure(api.CreateElement('annot'));
    api.AddAttribute(annotElement, 'type', 'xpath-test');

    // Process text content
    textWithFormatting = textObj.TextWithFormatting;
    for i = 0 to textWithFormatting.NumChildren {
        if (CharAt(textWithFormatting[i], 0) = '\') {
            textWithFormatting[i] = '';  // Remove formatting codes
        }
    }
    api.SetText(annotElement, JoinStrings(textWithFormatting, ''));

    return annotElement;
}
```
```

--------------------------------

### Line endid Attribute Placeholder

Source: https://github.com/music-encoding/sibmei/blob/develop/ExportHandlers.md

Use the 'endid' attribute with placeholders like 'PreciseMatch' to automatically add ID references for line objects based on their end position.

```javascript
@Element('Line', @Attrs(
    'func', 'coloration',
    'endid', 'PreciseMatch'
))
```

--------------------------------

### RegisterTextHandlers API

Source: https://context7.com/music-encoding/sibmei/llms.txt

Registers handlers for text objects based on their StyleId or StyleAsText properties to define how different text styles are converted to MEI elements.

```APIDOC
## api.RegisterTextHandlers()

### Description
Registers handlers for text objects based on their StyleId or StyleAsText properties. Used to define how different text styles are converted to MEI elements.

### Method
`api.RegisterTextHandlers(identifierType, handlerName, dictionary)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **identifierType** (string) - Required - Specifies whether to use 'StyleId' (for built-in styles) or 'StyleAsText' (for user-defined styles).
- **handlerName** (string) - Required - The name of the handler to use (e.g., 'ControlEventTemplateHandler').
- **dictionary** (object) - Required - A dictionary mapping text styles to MEI element structures.

### Request Example
```js
// Register text handlers using StyleId (for built-in styles)
api.RegisterTextHandlers('StyleId', 'ControlEventTemplateHandler', CreateDictionary(
    'text.staff.technique', @Element('Dir', @Attrs('type', 'technique'),
        api.FormattedText
    )
));

// Register text handlers using StyleAsText (for user-defined styles)
api.RegisterTextHandlers('StyleAsText', 'ControlEventTemplateHandler', CreateDictionary(
    'My custom text', @Element('dir', null,
        @Element('anchoredText', @Attrs(), api.FormattedText)
    ),
    'Plain direction', @Element('dir', @Attrs(), api.UnformattedText)
));
```

### Response
None (This function modifies internal handler registrations).
```