Python phoneme alignment representation

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.

Table of contents

• Usage
  • Creating alignments
  • Accessing words and phonemes
  • Saving alignments
• Application programming interface (API)
  • pypar.Alignment
    • pypar.Alignment.__init__
    • pypar.Alignment.__add__
    • pypar.Alignment.__eq__
    • pypar.Alignment.__getitem__
    • pypar.Alignment.__len__
    • pypar.Alignment.__str__
    • pypar.Alignment.duration
    • pypar.Alignment.end
    • pypar.Alignment.find
    • pypar.Alignment.framewise_phoneme_indices
    • pypar.Alignment.phonemes
    • pypar.Alignment.phoneme_at_time
    • pypar.Alignment.phoneme_bounds
    • pypar.Alignment.save
    • pypar.Alignment.start
    • pypar.Alignment.update
    • pypar.Alignment.words
    • pypar.Alignment.word_bounds
  • pypar.Phoneme
    • pypar.Phoneme.__init__
    • pypar.Phoneme.__eq__
    • pypar.Phoneme.__str__
    • pypar.Phoneme.duration
    • pypar.Phoneme.end
    • pypar.Phoneme.start
  • pypar.Word
    • pypar.Word.__init__
    • pypar.Word.__eq__
    • pypar.Word.__getitem__
    • pypar.Word.__len__
    • pypar.Word.__str__
    • pypar.Word.duration
    • pypar.Word.end
    • pypar.Word.phoneme_at_time
    • pypar.Word.start
• Tests

Usage

Creating alignments

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/.

python alignment = pypar.Alignment(file)

Alignments can be created manually from Word and Phoneme objects. Start and end times are given in seconds.

```python

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.

```python

Slice

firsttwowords = alignment[:2]

Concatenate

alignmentwithrepeat = firsttwowords + alignment ```

Accessing words and phonemes

To 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.

```python

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.

Saving alignments

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.

Application programming interface (API)

pypar.Alignment

pypar.Alignment.__init__

```python 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
"""

```

pypar.Alignment.__add__

```python def add(self, other): """Add alignments by concatenation

Arguments
    other
        The alignment to compare to

Returns
    The concatenated alignment
"""

```

pypar.Alignment.__eq__

```python def eq(self, other) -> bool: """Equality comparison for alignments

Arguments
    other
        The alignment to compare to

Returns
    Whether the alignments are equal
"""

```

pypar.Alignment.__getitem__

```python 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
"""

```

pypar.Alignment.__len__

```python def len(self) -> int: """Retrieve the number of words

Returns
    The number of words in the alignment
"""

```

pypar.Alignment.__str__

```python def str(self) -> str: """Retrieve the text

Returns
    The words in the alignment separated by spaces
"""

```

pypar.Alignment.duration

```python def duration(self) -> float: """Retrieve the duration of the alignment in seconds

Returns
    The duration in seconds
"""

```

pypar.Alignment.end

```python def end(self) -> float: """Retrieve the end time of the alignment in seconds

Returns
    The end time in seconds
"""

```

pypar.Alignment.framewise_phoneme_indices

```python def framewisephonemeindices( 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
"""

```

pypar.Alignment.find

```python 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
"""

```

pypar.Alignment.phonemes

```python def phonemes(self) -> List[pypar.Phoneme]: """Retrieve the phonemes in the alignment

Returns
    The phonemes in the alignment
"""

```

pypar.Alignment.phoneme_at_time

```python def phonemeattime(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)
"""

```

pypar.Alignment.phoneme_bounds

```python def phonemebounds( self, samplerate: 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
"""

```

pypar.Alignment.save

```python 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
"""

```

pypar.Alignment.start

```python def start(self) -> float: """Retrieve the start time of the alignment in seconds

Returns
    The start time in seconds
"""

```

pypar.Alignment.update

```python 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
"""

```

pypar.Alignment.words

```python def words(self) -> List[pypar.Word]: """Retrieve the words in the alignment

Returns
    The words in the alignment
"""

```

pypar.Alignment.word_bounds

```python def wordattime(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
"""

```

pypar.Phoneme

pypar.Phoneme.__init__

```python 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
"""

```

pypar.Phoneme.__eq__

```python def eq(self, other) -> bool: """Equality comparison for phonemes

Arguments
    other
        The phoneme to compare to

Returns
    Whether the phonemes are equal
"""

```

pypar.Phoneme.__str__

```python def str(self) -> str: """Retrieve the phoneme text

Returns
    The phoneme
"""

```

pypar.Phoneme.duration

```python def duration(self) -> float: """Retrieve the phoneme duration

Returns
    The duration in seconds
"""

```

pypar.Phoneme.end

```python def end(self) -> float: """Retrieve the end time of the phoneme in seconds

Returns
    The end time in seconds
"""

```

pypar.Phoneme.start

```python def start(self) -> float: """Retrieve the start time of the phoneme in seconds

Returns
    The start time in seconds
"""

```

pypar.Word

pypar.Word.__init__

```python def init(self, word: str, phonemes: List[pypar.Phoneme]) -> None: """Create word

Arguments
    word
        The word
    phonemes
        The phonemes in the word
"""

```

pypar.Word.__eq__

```python def eq(self, other) -> bool: """Equality comparison for words

Arguments
    other
        The word to compare to

Returns
    Whether the words are the same
"""

```

pypar.Word.__getitem__

```python 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
"""

```

pypar.Word.__len__

```python def len(self) -> int: """Retrieve the number of phonemes

Returns
    The number of phonemes
"""

```

pypar.Word.__str__

```python def str(self) -> str: """Retrieve the word text

Returns
    The word text
"""

```

pypar.Word.duration

```python def duration(self) -> float: """Retrieve the word duration in seconds

Returns
    The duration in seconds
"""

```

pypar.Word.end

```python def end(self) -> float: """Retrieve the end time of the word in seconds

Returns
    The end time in seconds
"""

```

pypar.Word.phoneme_at_time

```python def phonemeattime(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)
"""

```

pypar.Word.start

```python def start(self) -> float: """Retrieve the start time of the word in seconds

    Returns
        The start time in seconds
    """

```

Tests

Tests can be run as follows.

pip install pytest pytest