The .ad file is an XML 1.0 document with UTF-8 encoding which conveys the submission to be described by CaptionSync along with optional additional processing directives such as notes to the describer, purchase order number, etc. To note that .ad files will only be processed after your Source tag is approved/configured by AST. The source will be inferred from the captioning submission.
Outline:
Since it is an XML 1.0 document, the simplest valid form would be something like this:
<Describe>
<CapASTid>1423193085username</CapASTid>
</Describe>
A more elaborate example would be:
<?xml version="1.0" encoding="UTF-8" ?>
<Describe>
<PO>N099044-CT</PO>
<CapASTid>1423193085username</CapASTid>
<Notes>The artist of paintings is Claude Monet</Notes>
<CallBack>http://67.34.45.122/lectures/post_results?
id=12387987983</CallBack>
</Describe>
Keep in mind that the contents of the document must be valid XML. i.e.
- < needs to be replaced with <
- > needs to be replaced with >
- & needs to be replaced with &
- XML tags are case sensitive
Required Tags:
A valid audio description XML document must have one CapASTid tag. The CapASTid tag must reference a submission which has associated video (i.e. not just an audio submission), the type of submission must be Captioning, and the submission was made less than 45 days ago or it was made via List of URLs submission or integration where the URL references the video.
CapASTid |
This must be an AST ID of a successful Captioning submission. e.g. <Describe> |
Optional Tags:
The following are optional tags for the audio description. All are optional, except possibly PO which would be required if the account is set up as requiring a purchase order and there is not a valid one defined to use as default.
Notes |
These are notes to help the describer regarding background on the video. <Describe> Be particularly mindful of making sure these notes to the describer are valid XML – speaker ID formats such as >> need to be marked up as >> for example. |
PO |
This is the purchase order number for the submission for accounts set up as requiring purchase orders. If not present, the submission will inherit the default or most recently used valid purchase order for the account via the web UI. <Describe> Keep in mind that the purchase order number needs to be nicely named -- no spaces, punctuation, or high ASCII characters please. |
CustReview |
This is the flag to specify if the customer should review the description before results are generated or not (Y or N). Normally the default from the web UI is used to determine if this will be requested. This tag can be used to override that default. <Describe> |
CallBack |
This tag tells AST where to send results files back to via HTTP or HTTPS POST for a particular description. This tag needs to be present with an approved Source tag, otherwise this tag will be ignored. <Describe> AST needs to approve the value of your Source tag in conjunction with your CallBack tag for any result posting to take place. This call back URL needs to be properly encoded e.g. %20 for SPACE. In addition, XML encoding may be required. For example The tag also needs to be less than 512 characters in length. If you need more than one result type returned for the description and/or you need to differentiate between different types of result files posted back (e.g. a VTT file and MP3 file) an additional {fileType} macro also needs to be present in the callback URL so that different posts can be completed for each result file. <Describe> This could result in posts URLs like: https://67.34.4.22/bio1/closedCaptioning?id=1283232 The specific file types of the macro expansion (e.g., closedCaptioning, transcript, etc.) will need to be configured by AST. |
ADStatusURL |
This tag tells AST where to send results files back to via HTTP or HTTPS POST with a Content-Transfer-Encoding of binary for a particular submission.. This tag needs to be present with an approved Source tag, otherwise this tag will be ignored. <ADrequest> This call back URL needs to be properly encoded e.g. %20 for SPACE. In addition, XML encoding may be required. For example The tag also needs to be less than 512 characters in length. The status information will be directly posted back to the specified URL as a raw POST with a MIME type of text/xml (note that there will not be any form URL encoding). The information will be presented in the following manner: <StatusUpdate> The status callback will be sent as soon as a fatal error occurs, but in general as far enough into the ingest processing to know that it is on track to succeed. For example, if an error occurs when attempting to find a media file, the status callback will be sent at that point. Otherwise the system will not send the status callback until processing has been completed and an AST ID has been assigned. Note that in the case of a malformed .ad file, no callback will be made, rather an email will be sent to the account holder (provided the account holder has not deselected that email type in Contact Settings via the web UI). Type The will be one of Initial or Update. A status callback of the type of Update will only occur where a submission which was successfully ingested, subsequently fails or is rejected (the result will be FAILURE). Result It will be one of IN_PROCESS, NOT_INGESTED, or FAILURE. A status callback with a result of FAILURE will only occur where a submission which was successfully ingested, subsequently fails or is rejected (the type will be Update). <StatusUpdate> <Type>Update</Type> <Result>FAILURE</Result> <ASTid>AD1312468614joe</ASTid> <ASTstatus>Rejected Media</ASTstatus> <ErrDetail>No video.</ErrDetail> </StatusUpdate> ASTid The tag will not be present for the Result of NOT_INGESTED, otherwise it will reference the CaptionSync AST ID of the submission. ASTstatus The tag will not be present for the Result of NOT_INGESTED, otherwise it will reference the current CaptionSync AST status of the submission. ErrDetail The tag will only be present for the Result of NOT_INGESTED and FAILURE. <StatusUpdate> <Type>Initial</Type> <Result>NOT_INGESTED</Result> <ErrDetail>Invalid .adrequest file - Purchase Order Number required, but no <PO> tag or valid default PO.</ErrDetail> </StatusUpdate> It is important to consider the possibility that the callback itself fails and no status information about the submission is received (e.g. 500 Internal Server Error). If no status information is received, it is important not to make assumptions about the status, rather further investigation is required. |
Note that this article corresponds to "AD XML Layout v3.pdf".
Comments
0 comments
Please sign in to leave a comment.