# Macros

You can use macros to set dynamic values for some configuration parameters. For example, when you write files to disk, you can configure the file names to include video timestamps.

## System, Session, and Source Macros

These macros provide information about the system, session, and the source media. You can use these macros with the image encoder, MPEG encoder, output engines, and with the enroll analysis engine.

Macro | Description
--- | ---
`%currentTime.TIME_FORMAT%` | The time, according the clock on the Media Server host, at which the macro is expanded. (Replace `TIME_FORMAT` with one of the time formats. For example, use `%currentTime.iso8601%` to obtain a timestamp in ISO 8601 format).
`%session.token%` | The token that identifies the `process` action sent to Media Server.
`%source.estimatedDuration%` | The estimated duration of the source media, when you ingest media with the video ingest engine.
`%source.filename%` | The file name of the source media file.
`%source.filename.stem%` | The file name of the source media file, but without the file extension.
`%source.mimeType%` | The MIME type of the source media.
`%source.pages%` | The number of pages contained in the source media, when you ingest media with the image ingest engine.
`%source.name%` | The name of the media source, equivalent to `%source.path%` for files and `%source.url%` for streams.
`%source.path%` | The full path of the source media file, including the file name.
`%source.url%` | The URL of the source.
`%system.hostname%` | The host name of the machine that Media Server is running on.
`%system.platform%` | The name of the operating system that Media Server is running on.
`%system.port%` | The Media Server ACI port.
`%uuid%` | A unique ID.

## Segment Macros

Segment macros represent the properties of a video segment. You can use the following macros with:

- The image encoder (images can be considered as short video segments).
- The MPEG encoder (when you set `Segment=TRUE`).
- An output task that outputs information about a video segment (for example an XML output task with `Mode=time`, `Mode=event`, or `Mode=bounded`).

Macro | Description
--- | ---
`%segment.startTime.TIME_FORMAT%` | The time when the segment starts, according to the timestamps in the video.
`%segment.peakTime.TIME_FORMAT%` |
`%segment.endTime.TIME_FORMAT%` | The time when the segment ends, according to the timestamps in the video.
`%segment.duration%` | The amount of video content that the segment contains, in milliseconds.
`%segment.sequence%` | A number that indicates the position of the segment in the video (counts up from 1).
`%segment.type%` | (Output tasks only) Expands to "pre", "post", or "failed": `pre` - the XML was output before the XSL transformation was applied. `post` - the data was output after the transformation was applied. `failed` - the data was output because it failed to reach its destination.
`%segment.pageNumber%` | The page number, in the source image or document.

## Record Macros

The macros in this section take values from Media Server records.

Macro | Description
--- | ---
`%record.track.name%` | The name of the track from which the record originated.
`%record.startTime.TIME_FORMAT%` | The time at which the record starts.
`%record.peakTime.TIME_FORMAT%` | For engines that perform integration, the time at which the best source frame occurred.
`%record.endTime.TIME_FORMAT%` | The time at which the record ends.
`%record.pageNumber%` | The page number, in the source image or document, that the record is associated with.
`%record.VALUE%` | Information from the record, where `VALUE` is the path to the desired property. The path can be constructed from property names or property types.

The following sections list the macros supported by Media Server data types.

AudioData

    %record.AudioData.sampleRate%
    %record.AudioData.channels%

ClassificationData

    %record.ClassificationData.confidence%
    %record.ClassificationData.identifier%
    %record.ClassificationData.metadata.key%

where `key` is the key for a metadata key-value pair associated with the object class.

FaceData

    %record.FaceData.region.left%
    %record.FaceData.region.top%
    %record.FaceData.region.width%
    %record.FaceData.region.height%
    %record.FaceData.outofplaneanglex%
    %record.FaceData.outofplaneangley%
    %record.FaceData.ellipse.center.x%
    %record.FaceData.ellipse.center.y%
    %record.FaceData.ellipse.a%
    %record.FaceData.ellipse.b%
    %record.FaceData.ellipse.angle%
    %record.FaceData.lefteye.center.x%
    %record.FaceData.lefteye.center.y%
    %record.FaceData.lefteye.radius%
    %record.FaceData.righteye.center.x%
    %record.FaceData.righteye.center.y%
    %record.FaceData.righteye.radius%

Faces are a type of `RegionData`, so you can also use:

    %record.RegionData.left%
    %record.RegionData.top%
    %record.RegionData.width%
    %record.RegionData.height%

IdentityData

    %record.IdentityData.confidence%
    %record.IdentityData.identifier%
    %record.IdentityData.database%
    %record.IdentityData.metadata.key%

where `key` is the key for a metadata key-value pair in the database.

ImageData

    %record.ImageData.compressionQuality%
    %record.ImageData.format%
    %record.ImageData.width%
    %record.ImageData.height%
    %record.ImageData.pixelAspectRatio% (deprecated)

RectangleData

    %record.RectangleData.left%
    %record.RectangleData.top%
    %record.RectangleData.width%
    %record.RectangleData.height%

Rectangles are a type of `RegionData`, so you can also use:

    %record.RegionData.left%
    %record.RegionData.top%
    %record.RegionData.width%
    %record.RegionData.height%

PointData

    %record.PointData.x%
    %record.PointData.y%

PolygonData

    %record.PolygonData.polygon%
    %record.PolygonData.left%
    %record.PolygonData.top%
    %record.PolygonData.width%
    %record.PolygonData.height%

Polygons are a type of `RegionData`, so you can also use:

    %record.RegionData.left%
    %record.RegionData.top%
    %record.RegionData.width%
    %record.RegionData.height%

ProxyData

    %record.ProxyData.pages% (when you ingest media with the image ingest engine)
    %record.ProxyData.estimatedDuration% (when you ingest media with the video ingest engine)
    %record.ProxyData.displayHeight%
    %record.ProxyData.displayWidth%
    %record.ProxyData.filename%
    %record.ProxyData.name%
    %record.ProxyData.path%
    %record.ProxyData.url%
    %record.ProxyData.mimeType%
    %record.ProxyData.streams.audioStream[1].channels%
    %record.ProxyData.streams.audioStream[1].sampleRate%
    %record.ProxyData.streams.audioStream[1].format%
    %record.ProxyData.streams.audioStream[1].codec%
    %record.ProxyData.streams.audioStream[1].language%
    %record.ProxyData.streams.videoStream[1].width%
    %record.ProxyData.streams.videoStream[1].height%
    %record.ProxyData.streams.videoStream[1].sar% (Source Aspect Ratio)
    %record.ProxyData.streams.videoStream[1].codec%
    %record.ProxyData.streams.videoStream[1].horizontalDPI% (image ingest only)
    %record.ProxyData.streams.videoStream[1].verticalDPI%   (image ingest only)
    %record.ProxyData.metadata.key%

where `key` is the key for a metadata key-value pair associated with the proxy information.

TextData

    %record.TextData%

TrackingEventData

    %record.TrackingEventData.eventType%
    %record.TrackingEventData.elapsedMicroSeconds%

UUIDData

    %record.UUIDData%

## Record Macros Example

Consider the following XML produced by face recognition:

    <FaceRecognitionResult>
      <face>
        ...
        <region>
          <height>258</height>
          <left>341</left>
          <top>208</top>
          <width>258</width>
        </region>
        ...
      </face>
      <id>693e7de5-9974-4acf-9b202b8caf212c10</id>
      <identity>
        <confidence>76.3419418</confidence>
        <database>Faces</database>
        <identifier>Person01</identifier>
      </identity>
    </FaceRecognitionResult>

To extract the UUID for the record, you could use the following:

- `%record.FaceRecognitionResult.id%`.
- `%record.id%`, because you can omit the highest level in the XML (`FaceRecognitionResult`). Omitting the output track type means that this macro would also work with records produced by face detection.
- `%record.UUIDData%` is even more generic, because Media Server looks for the first element of type `UUIDData`, rather than an element explicitly named `id`.

To extract the name of the person recognized by face recognition, you could use the following:

- `%record.FaceRecognitionResult.identity.identifier%`
- `%record.identity.identifier%`, because you can omit the highest level in the XML (`FaceRecognitionResult`).
- `%record.IdentityData.identifier%` is even more generic, because Media Server looks for the first element of type `IdentityData`, rather than an element explicitly named `identity`.

_FT_HTML5_bannerTitle.htm