Constructor
new LabbcatEdit(baseUrl, username, password)
Create a store client
Parameters:
Name |
Type |
Description |
baseUrl |
string
|
The LaBB-CAT base URL (i.e. the address of the 'home' link) |
username |
string
|
The LaBB-CAT user name. |
password |
string
|
The LaBB-CAT password. |
- Author:
-
- Robert Fromont robert@fromont.net.nz
- Source:
Example
// create annotation store client
const store = new LabbcatEdit("https://labbcat.canterbury.ac.nz", "demo", "demo");
// get a corpus
store.getCorpusIds((corpora, errors, messages, call)=>{
console.log("transcripts in: " + corpora[0]);
store.getTranscriptIdsInCorpus(corpora[0], (ids, errors, messages, call, id)=>{
console.log("Deleting all transcripts in " + id));
for (i in ids) {
store.deleteTranscript(ids[i], (ids, errors, messages, call, id)=>{
console.log("deleted " + id);
});
}
});
});
Extends
Members
baseUrl
The base URL - e.g. https://labbcat.canterbury.ac.nz/demo/api/store/
- Overrides:
- Source:
storeEditUrl
The graph store URL - e.g. https://labbcat.canterbury.ac.nz/demo/api/edit/store/
- Source:
storeUrl
The graph store URL - e.g. https://labbcat.canterbury.ac.nz/demo/api/store/
- Overrides:
- Source:
username
The LaBB-CAT user name.
- Overrides:
- Source:
Methods
allUtterances(participantIds, transcriptTypesopt, mainParticipantopt, onResult)
Identifies all utterances by the given participants.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
participantIds |
Array.<string>
|
|
|
A list of participant IDs to identify
the utterances of. |
transcriptTypes |
Array.<string>
|
<optional>
|
null
|
An optional list of transcript types to limit
the results to. If null, all transcript types will be searched. |
mainParticipant |
boolean
|
<optional>
|
true
|
true to search only main-participant
utterances, false to search all utterances. |
onResult |
resultCallback
|
|
|
Invoked when the request has returned a
result which will be: An object with one attribute, "threadId",
which identifies the resulting task, which can be passed to
LabbcatView#getMatches, LabbcatView#taskStatus,
LabbcatView#waitForTask, etc. |
- Overrides:
- Source:
cancelTask(threadId, onResult)
Cancels a running task.
Parameters:
Name |
Type |
Description |
threadId |
|
The ID of the task. |
onResult |
resultCallback
|
Invoked when the request has completed. |
- Overrides:
- Source:
countAnnotations(id, layerId, maxOrdinalopt, onResult)
Gets the number of annotations on the given layer of the given transcript.
Parameters:
Name |
Type |
Attributes |
Description |
id |
string
|
|
The ID of the transcript. |
layerId |
string
|
|
The ID of the layer. |
maxOrdinal |
int
|
<optional>
|
The maximum ordinal for the counted annotations.
e.g. a maxOrdinal of 1 will ensure that only the first annotation for each
parent is counted. If maxOrdinal is null, then all annotations are
counted, regardless of their ordinal. |
onResult |
resultCallback
|
|
Invoked when the request has returned a
result which will be: A (possibly empty) array of annotations. |
- Overrides:
- Source:
countMatchingAnnotations(expression, onResult)
Counts the number of annotations that match a particular pattern.
Parameters:
Name |
Type |
Description |
expression |
string
|
An expression that determines which participants match.
The expression language is loosely based on JavaScript; expressions such as
the following can be used:
id == 'ew_0_456'
!/th[aeiou].//.test(label)
first('participant').label == 'Robert' && first('utterances').start.offset ==
12.345
graph.id == 'AdaAicheson-01.trs' && layer.id == 'orthography'
&& start.offset > 10.5
previous.id == 'ew_0_456'
NB all expressions must match by either id or layer.id. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: The number of matching annotations. |
- Overrides:
- Source:
countMatchingParticipantIds(expression, onResult)
Counts the number of participants that match a particular pattern.
Parameters:
Name |
Type |
Description |
expression |
string
|
An expression that determines which participants match.
The expression language is loosely based on JavaScript; expressions such as the
following can be used:
/Ada.+/.test(id)
labels('corpus').includes('CC')
labels('participant_languages').includes('en')
labels('transcript_language').includes('en')
!/Ada.+/.test(id) && first('corpus').label == 'CC'
all('transcript_rating').length > 2
all('participant_rating').length = 0
!annotators('transcript_rating').includes('labbcat')
first('participant_gender').label == 'NA'
|
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: The number of matching participants. |
- Overrides:
- Source:
countMatchingTranscriptIds(expression, onResult)
Counts the number of transcripts that match a particular pattern.
Parameters:
Name |
Type |
Description |
expression |
string
|
An expression that determines which transcripts match.
The expression language is loosely based on JavaScript; expressions such as
the following can be used:
/Ada.+/.test(id)
labels('participant').includes('Robert')
('CC', 'IA', 'MU').includes(first('corpus').label)
first('episode').label == 'Ada Aitcheson'
first('transcript_scribe').label == 'Robert'
first('participant_languages').label == 'en'
first('noise').label == 'bell'
labels('transcript_languages').includes('en')
labels('participant_languages').includes('en')
labels('noise').includes('bell')
all('transcript_languages').length gt; 1
all('participant_languages').length gt; 1
all('transcript').length gt; 100
annotators('transcript_rating').includes('Robert')
!/Ada.+/.test(id) && first('corpus').label == 'CC' &&
labels('participant').includes('Robert')
|
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: The number of matching transcripts. |
- Overrides:
- Source:
deleteParticipant(id, onResult)
Deletes the given participan, and all assciated meta-data, from the graph store.
Parameters:
Name |
Type |
Description |
id |
string
|
The participant ID |
onResult |
resultCallback
|
Invoked when the request has completed. |
- Source:
deleteTranscript(id, onResult)
Deletes the given transcript, and all associated media, from the graph store.
Parameters:
Name |
Type |
Description |
id |
string
|
The transcript ID |
onResult |
resultCallback
|
Invoked when the request has completed. |
- Source:
dictionaryAdd(layerId, label, entry, onResult)
For HTK dictionary-filling, this adds a new dictionary entry and updates all tokens.
Parameters:
Name |
Type |
Description |
layerId |
string
|
The dictionary of this layer will be used. |
label |
string
|
The word label to add an entry for. |
entry |
string
|
The definition (pronunciation) of the word to add. |
onResult |
resultCallback
|
Invoked when the request has returned a
result. |
- Source:
dictionaryLookup(layerId, labels, onResult)
For HTK dictionary-filling, this looks up some given words to get their entries.
Parameters:
Name |
Type |
Description |
layerId |
string
|
The dictionary of this layer will be used. |
labels |
string
|
Space-separated list of words to look up. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: an object with the following structure:
returned has the following structure:
- words - object where each key is the word, and each value is an
array of entries for that word
- combined - the first entry of each word, concatenated together
with a hyphen separator
|
- Overrides:
- Source:
dictionarySuggest(layerId, labels, onResult)
For HTK dictionary-filling, this uses a layer dictionary to suggest missing entries.
Parameters:
Name |
Type |
Description |
layerId |
string
|
The dictionary of this layer will be used. |
labels |
string
|
Space-separated list of words to suggest entries for. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: an object with the following structure:
returned has the following structure:
- words - object where each key is the word, and each value is a
array of suggestions for that word (with 0 or 1 elements)
|
- Overrides:
- Source:
getAnchors(id, anchorIds, onResult)
Gets the given anchors in the given transcript.
Parameters:
Name |
Type |
Description |
id |
string
|
The given transcript ID. |
anchorIds |
Array.<string>
|
The IDs of the anchors to load. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: The identified transcript. |
- Overrides:
- Source:
getAnnotations(id, layerId, maxOrdinalopt, pageLengthopt, pageNumberopt, onResult)
Gets the annotations on the given layer of the given transcript.
Parameters:
Name |
Type |
Attributes |
Description |
id |
string
|
|
The ID of the transcript. |
layerId |
string
|
|
The ID of the layer. |
maxOrdinal |
int
|
<optional>
|
The maximum ordinal for the returned annotations.
e.g. a maxOrdinal of 1 will ensure that only the first annotation for each
parent is returned. If maxOrdinal is null, then all annotations are
returned, regardless of their ordinal. |
pageLength |
int
|
<optional>
|
The maximum number of IDs to return, or null to return all. |
pageNumber |
int
|
<optional>
|
The zero-based page number to return, or null to return
the first page. |
onResult |
resultCallback
|
|
Invoked when the request has returned a
result which will be: A (possibly empty) array of annotations. |
- Overrides:
- Source:
getAnnotatorDescriptors(onResult)
Lists the descriptors of all registered annotators.
Annotators are modules that perform automated annotation of transcripts.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: A list of the descriptors of all registered
annotators. |
- Overrides:
- Source:
getAnnotatorTaskParameters(taskId, onResult)
Supplies the given task's parameter string.
Parameters:
Name |
Type |
Description |
taskId |
string
|
The ID of the task, which must not already exist. |
onResult |
resultCallback
|
Invoked when the request has returned a
result, which is the task parameters, serialized as a string. |
- Overrides:
- Source:
getAnnotatorTasks(annotatorId, onResult)
Supplies a list of automation tasks for the identified annotator.
Parameters:
Name |
Type |
Description |
annotatorId |
string
|
The ID of the annotator that will perform the task. |
onResult |
resultCallback
|
Invoked when the request has returned a
result, which is a map of task IDs to descriptions. |
- Overrides:
- Source:
List the media available for the given transcript.
Parameters:
Name |
Type |
Description |
id |
string
|
The transcript ID. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: List of media files available for the given transcript. |
- Overrides:
- Source:
getCorpusIds(onResult)
Gets a list of corpus IDs.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: {string[]} A list of corpus IDs. |
- Overrides:
- Source:
getDeserializerDescriptors(onResult)
Lists the descriptors of all registered deserializers.
Deserializers are modules that import annotation structures from a specific file
format, e.g. Praat TextGrid, plain text, etc.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: A list of the descriptors of all registered
deserializers. |
- Overrides:
- Source:
getEpisodeDocuments(id, onResult)
Get a list of documents associated with the episode of the given transcript.
Parameters:
Name |
Type |
Description |
id |
string
|
The transcript ID. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: List of media files available for the given transcript. |
- Overrides:
- Source:
getFragments(transcriptIds, startOffsets, endOffsets, layerIds, mimeType, diropt, onResult)
Get transcript fragments in a specified format.
For convenience, the first three arguments, transcriptIds,
startOffsets, and endOffsets, can be replaced by a single
array of match objects of the kind returned by LabbcatView#getMatches, in
which case the start/end times are the utterance boundaries - e.g.
labbcat.getMatches(threadId, wordsContext (result, e, m) => {
labbcat.getFragments(result.matches, layerIds, mimeType, dir, (files, e, m) => {
...
});
});
Parameters:
Name |
Type |
Attributes |
Description |
transcriptIds |
Array.<string>
|
|
A list of transcript IDs (transcript names). |
startOffsets |
Array.<float>
|
|
A list of start offsets, with one element for
each element in transcriptIds. |
endOffsets |
Array.<float>
|
|
A list of end offsets, with one element for each element in
transcriptIds. |
layerIds |
Array.<string>
|
|
A list of IDs of annotation layers to include in the
fragment. |
mimeType |
string
|
|
The desired format, for example "text/praat-textgrid" for Praat
TextGrids, "text/plain" for plain text, etc. |
dir |
string
|
<optional>
|
A directory in which the files should be stored, or null
for a temporary folder. If specified, and the directory doesn't exist, it will
be created. |
onResult |
resultCallback
|
|
Invoked when the request has returned a
result which will be: A list of files. If dir is null,
these files will be stored under the system's temporary directory, so once
processing is finished, they should be deleted by the caller, or moved to a
more permanent location. |
- Overrides:
- Source:
getId(onResult)
Gets the store's ID.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: {string} The annotation store's ID. |
- Overrides:
- Source:
getInfo(onResult)
Gets the store's information document.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: {string} An HTML document providing
information about the corpus. |
- Overrides:
- Source:
getLayer(id, onResult)
Gets a layer definition.
Parameters:
Name |
Type |
Description |
id |
string
|
ID of the layer to get the definition for. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: The definition of the given layer. |
- Overrides:
- Source:
getLayerIds(onResult)
Gets a list of layer IDs (annotation 'types').
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: {string[]} A list of layer IDs. |
- Overrides:
- Source:
getLayerManagers(onResult)
Gets a list of currently-installed layer managers.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: an array of objects with the following
structure:
-
layer_manager_id : ID of the layer manager.
-
version : The version of the installed implementation.
-
name : The name for the layer manager.
-
description : A brief description of what the layer manager does.
-
layer_type : What kinds of layers the layer manager can process - a
string composed of any of the following:
- S - segment layers
- W - word layers
- M - phrase (meta) layers
- F - span (freeform) layers
|
- Overrides:
- Source:
getLayers(onResult)
Gets a list of layer definitions.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: A list of layer definitions. |
- Overrides:
- Source:
getMatchAnnotations(matchIds, layerIds, targetOffsetopt, annotationsPerLayeropt, onResult)
Gets annotations on selected layers related to search results returned by a previous
call to
LabbcatView#getMatches.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
matchIds |
Array.<string>
|
Array.<object>
|
|
|
A list of MatchIds, or a list of match
objects returned by LabbcatView#getMatches |
layerIds |
Array.<string>
|
|
|
A list of layer IDs. |
targetOffset |
int
|
<optional>
|
0
|
The distance from the original target of the match, e.g.
- 0 - find annotations of the match target itself
- 1 - find annotations of the token immediately after match target
- -1 - find annotations of the token immediately before match target
|
annotationsPerLayer |
int
|
<optional>
|
1
|
The number of annotations on the given layer to
retrieve. In most cases, there's only one annotation available. However, tokens may,
for example, be annotated with `all possible phonemic transcriptions', in which case
using a value of greater than 1 for this parameter provides other phonemic
transcriptions, for tokens that have more than one. |
onResult |
resultCallback
|
|
|
Invoked when the request has returned a
result which will be: An array of arrays of Annotations, of
dimensions matchIds.length × (layerIds.length *
annotationsPerLayer). The first index matches the corresponding
index in matchIds. |
- Overrides:
- Source:
getMatches(threadId, wordsContextopt, pageLengthopt, pageNumberopt, onResult)
Gets a list of tokens that were matched by
LabbcatView#search.
If the task is still running, then this function will wait for it to finish.
This means calls can be stacked like this:
const matches = labbcat.getMatches(
labbcat.search(
{"orthography", "and"},
participantIds, true), 1);
Parameters:
Name |
Type |
Attributes |
Default |
Description |
threadId |
string
|
|
|
A task ID returned by LabbcatView#search. |
wordsContext |
int
|
<optional>
|
0
|
Number of words context to include in the Before
Match and After Match columns in the results. |
pageLength |
int
|
<optional>
|
|
The maximum number of matches to return, or null to
return all. |
pageNumber |
int
|
<optional>
|
|
The zero-based page number to return, or null to
return the first page. |
onResult |
resultCallback
|
|
|
Invoked when the request has returned a
result which will be: An object with two attributes:
- name
- The name of the search results collection
- matches
- A list of match objects, with the following attributes
- MatchId
- A string identifying the match, of the kind expected
by LabbcatView#getMatchAnnotations
- Transcript
- The name of the transcript
- Participant
- The name of the participant
- Corpus
- The name of corpus the transcript belongs to
- Line
- The start offset of the utterance, usually in seconds
- LineEnd
- The end offset of the uttereance, usually in seconds
- BeforeMatch
- The context of the trascript text just before the
match
- Text
- The transcript text that matched
- AfterMatch
- The context of the transcript text just after
the match
|
- Overrides:
- Source:
getMatchingAnnotations(expression, pageLengthopt, pageNumberopt, onResult)
Gets a list of annotations that match a particular pattern.
Parameters:
Name |
Type |
Attributes |
Description |
expression |
string
|
|
An expression that determines which transcripts match.
The expression language is loosely based on JavaScript; expressions such as the
following can be used:
id == 'ew_0_456'
!/th[aeiou].//.test(label)
first('participant').label == 'Robert' && first('utterances').start.offset ==
12.345
graph.id == 'AdaAicheson-01.trs' && layer.id == 'orthography'
&& start.offset > 10.5
previous.id == 'ew_0_456'
NB all expressions must match by either id or layer.id. |
pageLength |
int
|
<optional>
|
The maximum number of annotations to return, or null
to return all. |
pageNumber |
int
|
<optional>
|
The zero-based page number to return, or null to
return the first page. |
onResult |
resultCallback
|
|
Invoked when the request has returned a
result which will be: A list of matching Annotations. |
- Overrides:
- Source:
getMatchingParticipantIds(expression, pageLengthopt, pageNumberopt, onResult)
Gets a list of IDs of participants that match a particular pattern.
Parameters:
Name |
Type |
Attributes |
Description |
expression |
string
|
|
An expression that determines which participants match.
The expression language is loosely based on JavaScript; expressions such as the
following can be used:
/Ada.+/.test(id)
labels('corpus').includes('CC')
labels('participant_languages').includes('en')
labels('transcript_language').includes('en')
!/Ada.+/.test(id) && first('corpus').label == 'CC'
all('transcript_rating').length > 2
all('participant_rating').length = 0
!annotators('transcript_rating').includes('labbcat')
first('participant_gender').label == 'NA'
|
pageLength |
int
|
<optional>
|
The maximum number of IDs to return, or null to return all. |
pageNumber |
int
|
<optional>
|
The zero-based page number to return, or null to return the
first page. |
onResult |
resultCallback
|
|
Invoked when the request has returned a
result which will be: A list of participant IDs. |
- Overrides:
- Source:
getMatchingTranscriptIds(expression, pageLengthopt, pageNumberopt, orderopt, onResult)
Gets a list of IDs of transcripts that match a particular pattern.
The results can be exhaustive, by omitting pageLength and pageNumber, or they
can be a subset (a 'page') of results, by given pageLength and pageNumber values.
The order of the list can be specified. If ommitted, the transcripts are
listed in ID order.
Parameters:
Name |
Type |
Attributes |
Description |
expression |
string
|
|
An expression that determines which transcripts match.
The expression language is loosely based on JavaScript; expressions such as
the following can be used:
/Ada.+/.test(id)
labels('participant').includes('Robert')
('CC', 'IA', 'MU').includes(first('corpus').label)
first('episode').label == 'Ada Aitcheson'
first('transcript_scribe').label == 'Robert'
first('participant_languages').label == 'en'
first('noise').label == 'bell'
labels('transcript_languages').includes('en')
labels('participant_languages').includes('en')
labels('noise').includes('bell')
all('transcript_languages').length gt; 1
all('participant_languages').length gt; 1
all('transcript').length gt; 100
annotators('transcript_rating').includes('Robert')
!/Ada.+/.test(id) && first('corpus').label == 'CC' &&
labels('participant').includes('Robert')
|
pageLength |
int
|
<optional>
|
The maximum number of IDs to return, or null to return all. |
pageNumber |
int
|
<optional>
|
The zero-based page number to return, or null to return
the first page. |
order |
string
|
<optional>
|
The ordering for the list of IDs, a string containing a
comma-separated list of
expressions, which may be appended by " ASC" or " DESC", or null for transcript ID order. |
onResult |
resultCallback
|
|
Invoked when the request has returned a
result which will be: A list of transcript IDs. |
- Overrides:
- Source:
Gets a given media track for a given transcript.
Parameters:
Name |
Type |
Attributes |
Description |
id |
string
|
|
The transcript ID. |
trackSuffix |
string
|
|
The track suffix of the media. |
mimeType |
string
|
|
The MIME type of the media. |
startOffset |
float
|
<optional>
|
The start offset of the media sample, or null for
the start of the whole recording. |
endOffset[ |
float
|
|
The end offset of the media sample, or null for the
end of the whole recording. |
onResult |
resultCallback
|
|
Invoked when the request has returned a
result which will be: {string} A URL to the given media for the given
transcript, or null if the given media doesn't exist. |
- Overrides:
- Source:
List the predefined media tracks available for transcripts.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: An ordered list of media track definitions. |
- Overrides:
- Source:
getParticipant(id, layerIds, onResult)
Gets the participant record specified by the given identifier.
Parameters:
Name |
Type |
Description |
id |
|
The ID of the participant, which could be their name or their
database annotation ID. |
layerIds |
|
The IDs of the participant attribute layers to load, or null if only
participant data is required. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: An annotation representing the participant,
or null if the participant was not found. |
- Overrides:
- Source:
getParticipantAttributes(participantIds, layerIds, fileName, onResult)
Gets participant attribute values for given participant IDs.
Parameters:
Name |
Type |
Description |
participantIds |
Array.<string>
|
A list of participant IDs. |
layerIds |
Array.<string>
|
A list of layer IDs corresponding to participant
attributes. In general, these are layers whose ID is prefixed 'participant_',
however formally it's any layer where layer.parentId == 'participant' &&
layer.alignment == 0. |
fileName |
string
|
The full path for the file where the results CSV
should be saved. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: The CSV file path - i.e. fileName
or null if the request failed. |
- Overrides:
- Source:
getParticipantIds(onResult)
Gets a list of participant IDs.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: {string[]} A list of participant IDs. |
- Overrides:
- Source:
getSchema(onResult)
Gets the layer schema.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: A schema defining the layers and how they
relate to each other. |
- Overrides:
- Source:
getSerializerDescriptors(onResult)
Lists the descriptors of all registered serializers.
Serializers are modules that export annotation structures as a specific file
format, e.g. Praat TextGrid, plain text, etc., so the mimeType of descriptors
reflects what mimeTypes can be specified for LabbcatView#getFragments.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: A list of the descriptors of all registered
serializers. |
- Overrides:
- Source:
getSoundFragments(transcriptIds, startOffsets, endOffsets, sampleRateopt, diropt, onResult)
Downloads WAV sound fragments.
For convenience, the first three arguments, transcriptIds,
startOffsets, and endOffsets, can be replaced by a single
array of match objects of the kind returned by LabbcatView#getMatches, in
which case the start/end times are the utterance boundaries - e.g.
labbcat.getMatches(threadId, wordsContext (result, e, m) => {
labbcat.getMatchAnnotations(result.matches, sampleRate, dir, (files, e, m) => {
...
});
});
Parameters:
Name |
Type |
Attributes |
Description |
transcriptIds |
Array.<string>
|
|
A list of transcript IDs (transcript names). |
startOffsets |
Array.<float>
|
|
A list of start offsets, with one element for each
element in transcriptIds. |
endOffsets |
Array.<float>
|
|
A list of end offsets, with one element for each element in
transcriptIds. |
sampleRate |
int
|
<optional>
|
The desired sample rate, or null for no preference. |
dir |
string
|
<optional>
|
A directory in which the files should be stored, or null
for a temporary folder. If specified, and the directory doesn't exist, it will
be created. |
onResult |
resultCallback
|
|
Invoked when the request has returned a
result which will be: A list of WAV files. If dir is
null, these files will be stored under the system's temporary directory, so
once processing is finished, they should be deleted by the caller, or moved to
a more permanent location. |
- Overrides:
- Source:
getSystemAttribute(attribute, onResult)
Gets the value of the given system attribute.
Parameters:
Name |
Type |
Description |
attribute |
string
|
Name of the attribute. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: The given attribute, with name and value properties. |
- Overrides:
- Source:
getTasks(onResult)
Gets list of tasks.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result, which is an map of task IDs to statuses. |
- Overrides:
- Source:
getTranscriberDescriptors(onResult)
Lists the descriptors of all registered transcribers.
Transcribers are modules that perform automated transcription of recordings
that have not alreadye been transcribed.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: A list of the descriptors of all registered
transcribers. |
- Overrides:
- Source:
getTranscript(id, layerIds, onResult)
Gets a transcript given its ID, containing only the given layers.
Parameters:
Name |
Type |
Description |
id |
string
|
The given transcript ID. |
layerIds |
Array.<string>
|
The IDs of the layers to load, or null for all
layers. If only transcript data is required, set this to ["graph"]. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: The identified transcript. |
- Overrides:
- Source:
getTranscriptAttributes(transcriptIds, layerIds, fileName, onResult)
Gets transcript attribute values for given transcript IDs.
Parameters:
Name |
Type |
Description |
transcriptIds |
Array.<string>
|
A list of transcript IDs (transcript names). |
layerIds |
Array.<string>
|
A list of layer IDs corresponding to transcript
attributes. In general, these are layers whose ID is prefixed 'transcript_',
however formally it's any layer where layer.parentId == 'graph' &&
layer.alignment == 0, which includes 'corpus' as well as transcript attribute layers. |
fileName |
string
|
The full path for the file where the results CSV
should be saved. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: The CSV file path - i.e. fileName
or null if the request failed. |
- Overrides:
- Source:
getTranscriptIds(onResult)
Gets a list of transcript IDs.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: {string[]} A list of transcript IDs. |
- Overrides:
- Source:
getTranscriptIdsInCorpus(id, onResult)
Gets a list of transcript IDs in the given corpus.
Parameters:
Name |
Type |
Description |
id |
string
|
A corpus ID. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: {string[]} A list of transcript IDs. |
- Overrides:
- Source:
getTranscriptIdsWithParticipant(id, onResult)
Gets a list of IDs of transcripts that include the given participant.
Parameters:
Name |
Type |
Description |
id |
string
|
A participant ID. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: {string[]} A list of transcript IDs. |
- Overrides:
- Source:
getUserInfo(onResult)
Gets information about the current user, including the roles or groups they are
in.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: The user record with an attribute called
"roles" which is an array of string role names. |
- Overrides:
- Source:
missingAnnotations(seriesId, tokenLayerId, annotationLayerId, onResult)
For HTK dictionary-filling, this starts a task (returning it's threadId) that
traverses the given utterances, looking for missing word pronunciations
Parameters:
Name |
Type |
Description |
seriesId |
string
|
search.search_id for identifying the utterances |
tokenLayerId |
string
|
token layer ("orthography") |
annotationLayerId |
string
|
tokens with missing annotations on this layer
should be returned ("phonemes") the "model" returned is the threadId of the task |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: the threadId of the task.
LabbcatView#taskStatus can be used to follow the progress of the task
until it's finished. Once done, the resultUrl can be invoked, which returns a
map from token labels to token IDs (one per type) i.e. the word that's missing,
with an ID for finding its first occurance |
- Overrides:
- Source:
newTranscript(transcript, media, mediaSuffixopt, transcriptType, corpus, episodeopt, onResult, onProgress)
Uploads a new transcript.
Parameters:
Name |
Type |
Attributes |
Description |
transcript |
file
|
string
|
|
The transcript to upload. In a browser, this
must be a file object, and in Node, it must be the full path to the file. |
media |
file
|
Array.<file>
|
string
|
Array.<string>
|
|
The media to upload, if any. In a
browser, these must be file objects, and in Node, they must be the full paths
to the files. |
mediaSuffix |
string
|
<optional>
|
The media suffix for the media. |
transcriptType |
string
|
|
The transcript type. |
corpus |
string
|
|
The corpus for the transcript. |
episode |
string
|
<optional>
|
The episode the transcript belongs to. |
onResult |
resultCallback
|
|
Invoked when the request has returned a
result, which is the task ID of the resulting annotation generation task. The
task status can be updated using LabbcatView#taskStatus |
onProgress |
|
|
Invoked on XMLHttpRequest progress. |
- Source:
praat(csv, transcriptColumn, participantColumn, startTimeColumn, endTimeColumn, windowOffset, passThroughData, measurementParameters, onResult, onProgress)
Process with Praat.
Parameters:
Name |
Type |
Description |
csv |
file
|
string
|
The results file to upload. In a browser, this
must be a file object, and in Node, it must be the full path to the file. |
transcriptColumn |
int
|
CSV column index of the transcript name. |
participantColumn |
int
|
CSV column index of the participant name. |
startTimeColumn |
int
|
CSV column index of the start time. |
endTimeColumn |
int
|
CSV column index of the end time name. |
windowOffset |
number
|
How much surrounsing context to include, in seconds. |
passThroughData |
boolean
|
Whether to include all CSV columns from the
input file in the output file. |
measurementParameters |
object
|
Parameters that define what to measure
and output. All parameters are optional, and include:
- extractF1 (boolean)
- Extract F1. (default: false)
- extractF2 (boolean)
- Extract F2. (default: false)
- extractF3 (boolean)
- Extract F3. (default: false)
- samplePoints (string)
- Space-delimited series of real
numbers between 0 and 1, specifying the proportional time points to measure
formant at. e.g. "0.5" will measure only the mid-point, "0 0.2 0.4 0.6 0.8 1"
will measure six points evenly spread across the duration of the segment,
etc. (default: "0.5")
- formantCeilingDefault (int)
- Maximum Formant by default. (default:
550)
- formantDifferentiationLayerId (string)
- Participant attribute
layer ID for differentiating formant settings; this will typically be
"participant_gender" but can be any participant attribute layer.
- formantOtherPattern (string[])
- Array of regular expression
strings to match against the value of that attribute identified by
formantDifferentiationLayerId. If the participant's attribute value
matches the pattern for an element in this array, the corresponding element in
formantCeilingOther will be used for that participant.
- formantCeilingOther (int[])
- Values to use as the formant ceiling
for participants who's attribute value matches the corresponding regular
expression in formantOtherPattern
- scriptFormant (string)
- Formant extraction script command.
(default: "To Formant (burg)... 0.0025 5 formantCeiling 0.025 50")
- useFastTrack (boolean)
- Use the FastTrack plugin to generate
optimum, smoothed formant tracks. (default: false)
- fastTrackDifferentiationLayerId (string)
- Participant attribute
layer ID for differentiating fastTrack settings; this will typically be
"participant_gender" but can be any participant attribute layer.
- fastTrackOtherPattern (string[])
- Array of regular expression
strings to match against the value of that attribute identified by
fastTrackDifferentiationLayerId. If the participant's attribute value
matches the pattern for an element in this array, the corresponding element in
fastTrackCeilingOther will be used for that participant.
- fastTrackLowestAnalysisFrequencyDefault (int)
- Fast Track lowest
analysis frequency by default.
- fastTrackLowestAnalysisFrequencyOther (int[])
- Values to use as
the Fast Track lowest analysis frequency for participants who's attribute
value matches the corresponding regular expression in
fastTrackOtherPattern.
- fastTrackHighestAnalysisFrequencyDefault (int)
- Fast Track highest
analysis frequency by default.
- fastTrackHighestAnalysisFrequencyOther (int[])
- Values to use as
the Fast Track highest analysis frequency for participants who's attribute
value matches the corresponding regular expression in
fastTrackOtherPattern.
- fastTrackTimeStep
- Fast Track time_step global setting.
- fastTrackBasisFunctions
- Fast Track basis_functions global setting - "dct".
- fastTrackErrorMethod
- Fast Track error_method global setting - "mae".
- fastTrackTrackingMethod
- Fast Track tracking_method parameter for trackAutoselectProcedure; "burg" or
"robust".
- fastTrackEnableF1FrequencyHeuristic ("true" or "false")
- Fast Track enable_F1_frequency_heuristic global setting.
- fastTrackMaximumF1FrequencyValue
- Fast Track maximum_F1_frequency_value global setting.
- fastTrackEnableF1BandwidthHeuristic
- Fast Track enable_F1_bandwidth_heuristic global setting.
- fastTrackMaximumF1BandwidthValue
- Fast Track maximum_F1_bandwidth_value global setting.
- fastTrackEnableF2BandwidthHeuristic ("true" or "false")
- Fast Track enable_F2_bandwidth_heuristic global setting.
- fastTrackMaximumF2BandwidthValue
- Fast Track maximum_F2_bandwidth_value global setting.
- fastTrackEnableF3BandwidthHeuristic ("true" or "false")
- Fast Track enable_F3_bandwidth_heuristic global setting..
- fastTrackMaximumF3BandwidthValue
- Fast Track maximum_F3_bandwidth_value global setting.
- fastTrackEnableF4FrequencyHeuristic ("true" or "false")
- Fast Track enable_F4_frequency_heuristic global setting.
- fastTrackMinimumF4FrequencyValue
- Fast Track minimum_F4_frequency_value global setting.
- fastTrackEnableRhoticHeuristic ("true" of "false")
- Fast Track enable_rhotic_heuristic global setting.
- fastTrackEnableF3F4ProximityHeuristic
- Fast Track enable_F3F4_proximity_heuristic global setting.
- fastTrackNumberOfSteps
- Fast Track number of steps.
- fastTrackNumberOfCoefficients
- Fast Track number of coefficients for the regression function.
- fastTrackNumberOfFormants
- Fast Track number of formants.
- fastTrackCoefficients ("true" or "false")
- Whether to return the regression coefficients from FastTrack.
- extractMinimumPitch (boolean)
- Extract minimum pitch.
(default: false)
- extractMeanPitch (boolean)
- Extract mean pitch. (default: false)
- extractMaximumPitch (boolean)
- Extract maximum pitch.
(default: false)
- pitchFloorDefault (int)
- Pitch Floor by default. (default: 60)
- pitchCeilingDefault (int)
- Pitch Ceiling by default. (default: 500)
- voicingThresholdDefault (number)
- Voicing Threshold by default.
(default: 0.5)
- pitchDifferentiationLayerId (string)
- Participant attribute
layer ID for differentiating pitch settings; this will typically be
"participant_gender" but can be any participant attribute layer.
- pitchOtherPattern (string[])
- Array of regular expression
strings to match against the value of that attribute identified by
pitchDifferentiationLayerId. If the participant's attribute value
matches the pattern for an element in this array, the corresponding element in
pitchFloorOther, pitchCeilingOther, and
voicingThresholdOther will be used for that participant.
- pitchFloorOther (int[])
- Values to use as the pitch floor
for participants who's attribute value matches the corresponding regular
expression in pitchOtherPattern
- pitchCeilingOther (int[])
- Values to use as the pitch ceiling
for participants who's attribute value matches the corresponding regular
expression in pitchOtherPattern
- voicingThresholdOther (int[])
- Values to use as the voicing threshold
for participants who's attribute value matches the corresponding regular
expression in pitchOtherPattern
- scriptPitch (string)
- Pitch extraction script command.
(default:
"To Pitch (ac)... 0 pitchFloor 15 no 0.03 voicingThreshold 0.01 0.35 0.14 pitchCeiling")
- extractMaximumIntensity (boolean)
- Extract maximum intensity.
(default: false)
- intensityPitchFloorDefault (int)
- Pitch Floor by default.
(default: 60)
- intensityDifferentiationLayerId (string)
- Participant attribute
layer ID for differentiating intensity settings; this will typically be
"participant_gender" but can be any participant attribute layer.
- intensityOtherPattern (string[])
- Array of regular expression
strings to match against the value of that attribute identified by
intensityDifferentiationLayerId. If the participant's attribute value
matches the pattern for an element in this array, the corresponding element in
intensityPitchFloorOther will be used for that participant.
- intensityPitchFloorOther (int[])
- Values to use as the pitch floor
for participants who's attribute value matches the corresponding regular
expression in intensityPitchOtherPattern
- scriptIntensity (string)
- Pitch extraction script command.
(default: "To Intensity... intensityPitchFloor 0 yes")
- extractCOG1 (boolean)
- Extract COG 1. (default: false)
- extractCOG2 (boolean)
- Extract COG 2. (default: false)
- extractCOG23 (boolean)
- Extract COG 2/3. (default: false)
- script (string)
- A user-specified custom Praat script to execute
on each segment.
- attributes (string[])
- A list of participant attribute layer IDs
to include as variables for the custom Praat script.
|
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: An object with one attribute,
threadId. |
onProgress |
|
Invoked on XMLHttpRequest progress. |
- Overrides:
- Source:
readOnlyCategories(class_id, pageNumberopt, pageLengthopt, onResult)
Reads a list of category records.
Parameters:
Name |
Type |
Attributes |
Description |
class_id |
string
|
|
What attributes to read; "transcript" or "participant". |
pageNumber |
int
|
<optional>
|
The zero-based page of records to return (if null, all
records will be returned). |
pageLength |
int
|
<optional>
|
The length of pages (if null, the default page length is 20). |
onResult |
resultCallback
|
|
Invoked when the request has returned a
result which will be: A list of category records with the following
attributes:
- class_id
- The class_id of the category.
- category
- The name/id of the category.
- description
- The description of the category.
- display_order
- Where the category appears among other categories.
|
- Overrides:
- Source:
releaseTask(id, onResult)
Releases a finished task so it no longer uses resources on the server.
Parameters:
Name |
Type |
Description |
id |
string
|
ID of the task. |
onResult |
resultCallback
|
Invoked when the request has completed. |
- Overrides:
- Source:
saveEpisodeDocument(id, url, onResult)
Saves the given document for the episode of the given transcript.
Parameters:
Name |
Type |
Description |
id |
string
|
The transcript ID |
url |
string
|
A URL to the document. |
onResult |
resultCallback
|
Invoked when the request has returned a result. |
- Source:
Saves the given media for the given transcript
Parameters:
Name |
Type |
Description |
id |
string
|
The transcript ID |
trackSuffix |
string
|
The track suffix of the media. |
mediaUrl |
string
|
A URL to the media content. |
onResult |
resultCallback
|
Invoked when the request has returned a result. |
- Source:
saveParticipant(id, label, attributes, onResult)
Saves a participant, and all its tags, to the graph store.
To change the ID of an existing participant, pass the old/current ID as the
id, and pass the new ID as the label.
If the participant ID does not already exist in the database, a new participant record
is created.
Parameters:
Name |
Type |
Description |
id |
string
|
The participant ID - either the unique internal database ID,
or their name. |
label |
string
|
The new ID (name) for the participant |
attributes |
object
|
Participant attribute values - the names are the
participant attribute layer IDs, and the values are the corresponding new
attribute values. The pass phrase for participant access can also be set by
specifying a "_password" attribute. |
onResult |
resultCallback
|
Invoked when the request has completed. |
- Source:
saveSource(id, url, onResult)
Saves the given source file (transcript) for the given transcript.
Parameters:
Name |
Type |
Description |
id |
string
|
The transcript ID |
url |
string
|
A URL to the transcript. |
onResult |
resultCallback
|
Invoked when the request has returned a result. |
- Source:
saveTranscript(transcript, onResult)
Saves changes to the given transcript annotation graph object, which was
previously returned from #getTranscript.
NB this not be confused with the methods that upload a file:
#newTranscript and #updateTranscript.
NB Currently only transcript attributes can be updated.
The graph can be partial e.g. include only some of the layers that the
stored version of the transcript contains.
Parameters:
Name |
Type |
Description |
transcript |
|
The transcript to save. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: true if changes were saved, false if there
were no changes to save. |
- Source:
- See:
-
search(pattern, participantQueryopt, transcriptQueryopt, mainParticipantOnlyopt, offsetThresholdopt, matchesPerTranscriptopt, overlapThresholdopt, onResult)
Searches for tokens that match the given pattern.
Although mainParticipantOnly, offsetThreshold and
matchesPerTranscript are all optional, if one of them is specified,
then all must be specified.
The pattern should match the structure of the search matrix in the
browser interface of LaBB-CAT. This is a JSON object with one attribute called
columns
, which is an array of JSON objects.
Each element in the columns
array contains am JSON object named
layers
, whose value is a JSON object for patterns to match on each layer, and
optionally an element named adj
, whose value is a number representing the
maximum distance, in tokens, between this column and the next column - if adj
is not specified, the value defaults to 1, so tokens are contiguous.
Each element in the layers
JSON object is named after the layer it matches, and
the value is a named list with the following possible attributes:
- pattern
- A regular expression to match against the label
- min
- An inclusive minimum numeric value for the label
- max
- An exclusive maximum numeric value for the label
- not
- TRUE to negate the match
- anchorStart
- TRUE to anchor to the start of the annotation on this layer
(i.e. the matching word token will be the first at/after the start of the matching
annotation on this layer)
- anchorEnd
- TRUE to anchor to the end of the annotation on this layer
(i.e. the matching word token will be the last before/at the end of the matching
annotation on this layer)
- target
- TRUE to make this layer the target of the search; the results will
contain one row for each match on the target layer
Examples of valid pattern objects include:
// words starting with 'ps...'
const pattern1 = {
"columns" : [
{
"layers" : {
"orthography" : {
"pattern" : "ps.*"
}
}
}
]};
// the word 'the' followed immediately or with one intervening word by
// a hapax legomenon (word with a frequency of 1) that doesn't start with a vowel
const pattern2 = {
"columns" : [
{
"layers" : {
"orthography" : {
"pattern" : "the"
}
}
"adj" : 2 },
{
"layers" : {
"phonemes" : {
"not" : true,
"pattern" : "[cCEFHiIPqQuUV0123456789~#\\$@].*"}
"frequency" {
"max" : "2"
}
}
}
]};
For ease of use, the function will also accept the following abbreviated forms:
// a single list representing a 'one column' search,
// and string values, representing regular expression pattern matching
const pattern3 = { orthography : "ps.*" };
// a list containing the columns (adj defaults to 1, so matching tokens are contiguous)
const pattrn4 = [{
orthography : "the"
}, {
phonemes : {
not : true,
pattern : "[cCEFHiIPqQuUV0123456789~#\\$@].*" },
frequency : {
max = "2" }
}];
Parameters:
Name |
Type |
Attributes |
Default |
Description |
pattern |
object
|
|
|
An object representing the pattern to search for, which
mirrors the Search Matrix in the browser interface. |
participantQuery |
Array.<string>
|
<optional>
|
null
|
An optional expression for
identifying participants to search the utterances of. This can be any
expression of the kind used with LabbcatView#getMatchingParticipantIds
e.g. "['AP2505_Nelson','AP2512_MattBlack','AP2515_ErrolHitt'].includes(id)" |
transcriptQuery |
Array.<string>
|
<optional>
|
null
|
An optional expression for
identifying transcripts to search the utterances of. This can be any
expression of the kind used with LabbcatView#getMatchingTranscriptIds
e.g. "['CC','ID'].includes(first('corpus').label)
&& first('transcript_type').label == 'wordlist'" |
mainParticipantOnly |
boolean
|
<optional>
|
true
|
true to search only main-participant
utterances, false to search all utterances. |
offsetThreshold |
int
|
<optional>
|
null
|
Optional minimum alignment confidence for
matching word or segment annotations. A value of 50 means that annotations that
were at least automatically aligned will be returned. Use 100 for
manually-aligned annotations only, and 0 or no value to return all matching
annotations regardless of alignment confidence. |
matchesPerTranscript |
int
|
<optional>
|
null
|
Optional maximum number of matches per
transcript to return. null means all matches. |
overlapThreshold |
int
|
<optional>
|
null
|
Optional percentage overlap with other
utterances before simultaneous speech is excluded. null means include
all overlapping utterances. |
onResult |
resultCallback
|
|
|
Invoked when the request has returned a
result which will be: An object with one attribute, "threadId",
which identifies the resulting task, which can be passed to
LabbcatView#getMatches, LabbcatView#taskStatus,
LabbcatView#waitForTask, etc. |
- Overrides:
- Source:
taskStatus(id, onResult)
Gets the status of a task.
Parameters:
Name |
Type |
Description |
id |
string
|
ID of the task. |
onResult |
resultCallback
|
Invoked when the request has returned a result. |
- Overrides:
- Source:
updateTranscript(transcript, suppressGeneration, onResult, onProgress)
Uploads a new version of an existing transcript.
NB this not be confused with the method that saves an annotation graph
object: #saveTranscript
Parameters:
Name |
Type |
Description |
transcript |
file
|
string
|
The transcript to upload. In a browser, this
must be a file object, and in Node, it must be the full path to the file. |
suppressGeneration |
boolean
|
(optional) false (the default) to run
automatic layer generation, true to suppress automatic layer generation. |
onResult |
resultCallback
|
Invoked when the request has returned a result,
which is the task ID of the resulting annotation generation task. The
task status can be updated using LabbcatView#taskStatus |
onProgress |
|
Invoked on XMLHttpRequest progress. |
- Source:
versionInfo(onResult)
Gets version information of all components of LaBB-CAT.
Parameters:
Name |
Type |
Description |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: {object} An object containing section objects
"System", "Formats", "Layer Managers", etc. each containing version information
for sub-components. e.g.
- result["System"]["LaBB-CAT"] is the overall LaBB-CAT version,
- result["System"]["nzilbb.ag"] is the overall annotation graph package
version,
- result["Formats"]["Praat TextGrid"] is version of the Praat TextGrid
conversion module,
- result["Layer Managers"]["HTK"] is version of the HTK Layer Manager, etc.
|
- Overrides:
- Source:
waitForTask(threadId, maxSeconds, onResult)
Wait for the given task to finish.
Parameters:
Name |
Type |
Description |
threadId |
string
|
The task ID. |
maxSeconds |
int
|
The maximum time to wait for the task, or 0 for forever. |
onResult |
resultCallback
|
Invoked when the request has returned a
result which will be: The final task status. To determine whether
the task finished or waiting timed out, check result.running, which
will be false if the task finished. |
- Overrides:
- Source: