pip install pypar
Word and phoneme alignment representation for speech tasks. This repo does
not perform forced word or phoneme alignment, but provides an interface
for working with the resulting alignment of a forced aligner, such as
pyfoal, or a manual alignment.
- Usage
- Application programming interface (API)
pypar.Alignmentpypar.Alignment.__init__pypar.Alignment.__add__pypar.Alignment.__eq__pypar.Alignment.__getitem__pypar.Alignment.__len__pypar.Alignment.__str__pypar.Alignment.durationpypar.Alignment.endpypar.Alignment.findpypar.Alignment.framewise_phoneme_indicespypar.Alignment.phonemespypar.Alignment.phoneme_at_timepypar.Alignment.phoneme_boundspypar.Alignment.savepypar.Alignment.startpypar.Alignment.updatepypar.Alignment.wordspypar.Alignment.word_bounds
pypar.Phonemepypar.Word
- Tests
If you already have the alignment saved to a json, mlf, or TextGrid
file, pass the name of the file. Valid examples of each format can be found in
test/assets/.
alignment = pypar.Alignment(file)Alignments can be created manually from Word and Phoneme objects. Start and
end times are given in seconds.
# Create a word from phonemes
word = pypar.Word(
'THE',
[pypar.Phoneme('DH', 0., .03), pypar.Phoneme('AH0', .03, .06)])
# Create a silence
silence = pypar.Word(pypar.SILENCE, pypar.Phoneme(pypar.SILENCE, .06, .16))
# Make an alignment
alignment = pypar.Alignment([word, silence])You can create a new alignment from existing alignments via slicing and concatenation.
# Slice
first_two_words = alignment[:2]
# Concatenate
alignment_with_repeat = first_two_words + alignmentTo retrieve a list of words in the alignment, use alignment.words().
To retrieve a list of phonemes, use alignment.phonemes(). The Alignment,
Word, and Phoneme objects all define .start(), .end(), and
.duration() methods, which return the start time, end time, and duration,
respectively. All times are given in units of seconds. These objects also
define equality checks via ==, casting to string with str(), and iteration
as follows.
# Iterate over words
for word in alignment:
# Access start and end times
assert word.duration() == word.end() - word.start()
# Iterate over phonemes in word
for phoneme in word:
# Access string representation
assert isinstance(str(phoneme), str)To access a word or phoneme at a specific time, pass the time in seconds to
alignment.word_at_time or alignment.phoneme_at_time.
To retrieve the frame indices of the start and end of a word or phoneme, pass
the audio sampling rate and hopsize (in samples) to alignment.word_bounds or
alignment.phoneme_bounds.
To save an alignment to disk, use alignment.save(file), where file is the
desired filename. pypar currently supports saving as a json or TextGrid
file.
def __init__(
self,
alignment: Union[str, bytes, os.PathLike, List[pypar.Word], dict]
) -> None:
"""Create alignment
Arguments
alignment
The filename, list of words, or json dict of the alignment
"""def __add__(self, other):
"""Add alignments by concatenation
Arguments
other
The alignment to compare to
Returns
The concatenated alignment
"""def __eq__(self, other) -> bool:
"""Equality comparison for alignments
Arguments
other
The alignment to compare to
Returns
Whether the alignments are equal
"""def __getitem__(self, idx: Union[int, slice]) -> pypar.Word:
"""Retrieve the idxth word
Arguments
idx
The index of the word to retrieve
Returns
The word at index idx
"""def __len__(self) -> int:
"""Retrieve the number of words
Returns
The number of words in the alignment
"""def __str__(self) -> str:
"""Retrieve the text
Returns
The words in the alignment separated by spaces
"""def duration(self) -> float:
"""Retrieve the duration of the alignment in seconds
Returns
The duration in seconds
"""def end(self) -> float:
"""Retrieve the end time of the alignment in seconds
Returns
The end time in seconds
"""def framewise_phoneme_indices(
self,
phoneme_map: Dict[str, int],
hopsize: float,
times: Optional[List[float]] = None
) -> List[int]:
"""Convert alignment to phoneme indices at regular temporal interval
Arguments
phoneme_map
Mapping from phonemes to indices
hopsize
Temporal interval between frames in seconds
times
Specified times in seconds to sample phonemes
"""def find(self, words: str) -> int:
"""Find the words in the alignment
Arguments
words
The words to find
Returns
The index of the start of the words or -1 if not found
"""def phonemes(self) -> List[pypar.Phoneme]:
"""Retrieve the phonemes in the alignment
Returns
The phonemes in the alignment
"""def phoneme_at_time(self, time: float) -> Optional[pypar.Phoneme]:
"""Retrieve the phoneme spoken at specified time
Arguments
time
Time in seconds
Returns
The phoneme at the given time (or None if time is out of bounds)
"""def phoneme_bounds(
self,
sample_rate: int,
hopsize: int = 1
) -> List[Tuple[int, int]]:
"""Retrieve the start and end frame index of each phoneme
Arguments
sample_rate
The audio sampling rate
hopsize
The number of samples between successive frames
Returns
The start and end indices of the phonemes
"""def save(self, filename: Union[str, bytes, os.PathLike]) -> None:
"""Save alignment to json
Arguments
filename
The location on disk to save the phoneme alignment json
"""def start(self) -> float:
"""Retrieve the start time of the alignment in seconds
Returns
The start time in seconds
"""def update(
self,
idx: int = 0,
durations: Optional[List[float]] = None,
start: Optional[float] = None
) -> None:
"""Update alignment starting from phoneme index idx
Arguments
idx
The index of the first phoneme whose duration is being updated
durations
The new phoneme durations, starting from idx
start
The start time of the alignment
"""def words(self) -> List[pypar.Word]:
"""Retrieve the words in the alignment
Returns
The words in the alignment
"""def word_at_time(self, time: float) -> Optional[pypar.Word]:
"""Retrieve the word spoken at specified time
Arguments
time
Time in seconds
Returns
The word spoken at the specified time
"""def __init__(self, phoneme: str, start: float, end: float) -> None:
"""Create phoneme
Arguments
phoneme
The phoneme
start
The start time in seconds
end
The end time in seconds
"""def __eq__(self, other) -> bool:
"""Equality comparison for phonemes
Arguments
other
The phoneme to compare to
Returns
Whether the phonemes are equal
"""def __str__(self) -> str:
"""Retrieve the phoneme text
Returns
The phoneme
"""def duration(self) -> float:
"""Retrieve the phoneme duration
Returns
The duration in seconds
"""def end(self) -> float:
"""Retrieve the end time of the phoneme in seconds
Returns
The end time in seconds
"""def start(self) -> float:
"""Retrieve the start time of the phoneme in seconds
Returns
The start time in seconds
"""def __init__(self, word: str, phonemes: List[pypar.Phoneme]) -> None:
"""Create word
Arguments
word
The word
phonemes
The phonemes in the word
"""def __eq__(self, other) -> bool:
"""Equality comparison for words
Arguments
other
The word to compare to
Returns
Whether the words are the same
"""def __getitem__(self, idx: int) -> pypar.Phoneme:
"""Retrieve the idxth phoneme
Arguments
idx
The index of the phoneme to retrieve
Returns
The phoneme at index idx
"""def __len__(self) -> int:
"""Retrieve the number of phonemes
Returns
The number of phonemes
"""def __str__(self) -> str:
"""Retrieve the word text
Returns
The word text
"""def duration(self) -> float:
"""Retrieve the word duration in seconds
Returns
The duration in seconds
"""def end(self) -> float:
"""Retrieve the end time of the word in seconds
Returns
The end time in seconds
"""def phoneme_at_time(self, time: float) -> Optional[pypar.Phoneme]:
"""Retrieve the phoneme at the specified time
Arguments
time
Time in seconds
Returns
The phoneme at the given time (or None if time is out of bounds)
""" def start(self) -> float:
"""Retrieve the start time of the word in seconds
Returns
The start time in seconds
"""Tests can be run as follows.
pip install pytest
pytest