feat: ability to ask for details of a format by format number

src/index.ts

@@ -384,6 +384,33 @@ export namespace Quantel {
 		}
 	}
 
+	export interface Formats {
+		[key: number]: FormatInfo,
+	}
+
+	export async function getFormats (): Promise<Formats> {
+		try {
+			await getISAReference()
+			let isaRef = await isaIOR
+			let formats: Formats = {}
+			for (let x = 0 ; x < 255 ; x++) {
+				let format: FormatInfo | null =
+					await quantel.getFormatInfo(isaRef, { formatNumber: x }).then((x: FormatInfo) => x, () => null)
+				if (format) {
+					formats[format.formatNumber] = format
+				}
+			}
+			return formats
+		} catch (err) {
+			if (err.message.indexOf('TRANSIENT') >= 0) { isaIOR = null }
+			if (err.message.indexOf('OBJECT_NOT_EXIST') >= 0) {
+				isaIOR = null
+				return getFormats()
+			}
+			throw err
+		}
+	}
+
 	async function checkServer (options: PortRef): Promise<ServerInfo> {
 		let servers = await quantel.getServers(await isaIOR)
 		let server = servers.find((x: ServerInfo) =>

src/scratch/rest_api.md

@@ -180,6 +180,31 @@ If it is necessary to search for the clip by, say, title, a query interface can
 
 A GET request to this path should return a JSON array listing documents matching the query and each element  contains a _clipID_. A wildcard character `*` can be used to match zero of more characters.
 
+## Formats
+
+To query information about format of a clip, including framerate and dimensions, use the format resource.
+
+    /:zoneID/format/:formatID
+
+The format ID can be found in the `AudioFormats` and `VideoFormats` property of a clip. Omit the `:formatID` to list all of the formats available in a zone (may take a couple of seconds). For example, to find out the details of video format `90`:
+
+    /default/format/90
+
+```JSON
+{
+	"type": "FormatInfo",
+	"formatNumber": 90,
+	"essenceType": "VideoFragment",
+	"frameRate": 25,
+	"height": 576,
+	"width": 720,
+	"samples": 0,
+	"formatName": "Legacy 9E Mpeg 40 576i25",
+	"layoutName": "720x576i25",
+	"compressionName": "Mpeg-2"
+}
+```
+
 ## Loading clips
 
 Clips consist of _fragments_. To play a _clip_, or a sub-clip of a clip, it is necessary to load fragments onto a port. To query all fragments:

src/server.ts

@@ -73,12 +73,12 @@ router.get('/:zoneID.json', async (ctx) => {
 
 router.get('/:zoneID/', async (ctx) => {
 	if (ctx.params.zoneID === 'default') {
-		ctx.body = [ 'server/', 'clip/' ]
+		ctx.body = [ 'server/', 'clip/', 'format/' ]
 	} else {
 		let zones = await Quantel.listZones()
 		let inTheZone = zones.find(z => z.zoneName === ctx.params.zoneID || z.zoneNumber.toString() === ctx.params.zoneID)
 		if (inTheZone) {
-			ctx.body = [ 'server/', 'clip/' ]
+			ctx.body = [ 'server/', 'clip/', 'format/' ]
 		} else {
 			ctx.status = 404
 			ctx.body = {
@@ -90,6 +90,38 @@ router.get('/:zoneID/', async (ctx) => {
 	}
 })
 
+router.get('/default/format/', async (ctx) => {
+	ctx.body = await Quantel.getFormats()
+})
+
+router.get('/default/format/:formatID', async (ctx) => {
+	if (isNaN(+ctx.params.formatID) || +ctx.params.formatID < 0 || +ctx.params.formatID > 65535) {
+		ctx.status = 400
+		ctx.body = {
+			status: 400,
+			message: 'Bad request. Format ID must be a non-negative short number.',
+			stack: ''
+		} as JSONError
+		return
+	}
+	try {
+		ctx.body = await Quantel.getFormatInfo({
+			formatNumber: +ctx.params.formatID
+		})
+	} catch (err) {
+		if (err.message.indexOf('BadIdent') >= 0) {
+			ctx.status = 404
+			ctx.body = {
+				status: 404,
+				message: `Not found. A format with identifier '${ctx.params.formatID}' was not found.`,
+				stack: ''
+			}
+		} else {
+			throw err
+		}
+	}
+})
+
 router.get('/default/server/', async (ctx) => {
 	ctx.body = await Quantel.getServers()
 })