CantoneseIPAOperator — IPA for Cantonese

cjklib.reading.operator.CantoneseIPAOperator is an experimental implementation of a transcription of Cantonese into the International Phonetic Alphabet (IPA).


  • Tones can be marked either with tone numbers (1-6), tone contour numbers (e.g. 55), IPA tone bar characters or IPA diacritics,
  • choice between high level and high falling tone for number marks,
  • flexible set of tones,
  • support for stop tones,
  • handling of variable vowel length for tone contours of stop tone syllables and
  • splitting of syllables into onset and rhyme.


CantonteseIPAOperator does not supply the same closed set of syllables as other ReadingOperators as IPA provides different ways to represent pronunciation. Because of that a user defined IPA syllable will not easily map to another transcription system and thus only basic support is provided for this direction.

This operator supplies an additional method getOnsetRhyme() which allows breaking down syllables into their onset and rhyme.


Tones in IPA can be expressed using different schemes. The following schemes are implemented here:

  • Numbers, tone numbers for the six-tone scheme,
  • ChaoDigits, numbers displaying the levels of tone contours, e.g. 55 for the high level tone,
  • IPAToneBar, IPA modifying tone bar characters, e.g. ɛw˥˥,
  • None, no support for tone marks

Implementational details

The operator comes with three different set of tones to accommodate the user but at the same time handle all different tone types. This setting is controlled by option 'stopTones', where 'none' will force the set of 7 basic tones, 'general' will add the three stop tones found in STOP_TONES, and 'explicit' will add one stop tone for each possible vowel length i.e. short and long, making up the maximum count of 13. Internally the set with explicit stop tones is used.


  • Robert S. Bauer, Paul K. Benedikt: Modern Cantonese Phonology

    (摩登廣州話語音學). Walter de Gruyter, 1997, ISBN 3-11-014893-5.

  • Robert S. Bauer: Hong Kong Cantonese Tone Contours. In: Studies in

    Cantonese Linguistics. Linguistic Society of Hong Kong, 1998, ISBN 962-7578-04-5.

See also

Modern Cantonese Phonology
Preview on Google Books.


class cjklib.reading.operator.CantoneseIPAOperator(**options)

Bases: cjklib.reading.operator.TonalIPAOperator

Provides an operator on strings of the Cantonese language written in the International Phonetic Alphabet (IPA).


  • Lang: Shed more light on tone sandhi in Cantonese language.
  • Impl: Implement diacritics for Cantonese Tones. On which part of the syllable should they be placed. Document.
  • Lang: Binyām 變音
  • Impl: What are the semantics of non-level tones given for unreleased stop finals? Take high rising Binyam into account.
  • options – extra options
  • dbConnectInst – instance of a DatabaseConnector, if none is given, default settings will be assumed.
  • toneMarkType – type of tone marks, one out of 'numbers', 'chaoDigits', 'ipaToneBar', 'diacritics', 'none'
  • missingToneMark – if set to 'noinfo' no tone information will be deduced when no tone mark is found (takes on value None), if set to 'ignore' this entity will not be valid.
  • firstToneName – tone for mark '1' under tone mark type 'numbers' for ambiguous mapping between tones ‘HighLevel’ or ‘HighFalling’ under syllables without stop tones. For the latter tone mark '1' will still resolve to ‘HighLevel’, ‘HighStopped’ or ‘HighStopped_Short’ and ‘HighStopped_Long’ depending on the value of option 'stopTones'.
  • stopTones – if set to 'none' the basic 6 (7) tones will be used and stop tones will be reported as one of them, if set to 'general' the three stop tones will be included, if set to 'explicit' the short and long forms will be explicitly supported.
Cantonese stop tone mapping to general level tones.
Cantonese stop tone mapping to general level tones with stop tones realised for explicit marking short/long pronunciation.
classmethod getBaseTone(tone)

Gets the base tone for stop tones. The returned tone is one out of TONES.

Parameter:tone (str) – tone
Return type:str
Returns:base tone
classmethod getDefaultOptions()
getExplicitTone(plainEntity, baseTone)

Gets the explicit tone for the given plain syllable and base tone.

In case the 6 (7) base tones are used, the stop tone value can be deduced from the given syllable. The stop tone returned will be even more precise in denoting the vowel length that influences the tone contour.

  • plainEntity (str) – syllable without tonal information
  • baseTone (str) – tone
Return type:



explicit tone

Raises InvalidEntityError:

if the entity is invalid.


Splits the given plain syllable into onset (initial) and rhyme (final).

Parameter:plainSyllable (str) – syllable in IPA without tone marks
Return type:tuple of str
Returns:tuple of syllable onset and rhyme
Raises InvalidEntityError:
 if the entity is invalid (e.g. syllable nucleus or tone invalid).
getPlainReadingEntities(*args, **kwargs)
getTonalEntity(plainEntity, tone)

Gets the base tone for the given tone mark.

Parameter:toneMark (str) – tone mark representation of the tone
Return type:str
Raises InvalidEntityError:
 if the toneMark does not exist.
getTones(*args, **kwargs)

Checks if the given plain syllable can occur with stop tones which is the case for syllables with unreleased finals.

Parameter:plainEntity (str) – entity without tonal information
Return type:bool
Returns:True if given syllable can occur with stop tones, False otherwise
isToneValid(plainEntity, tone)

Checks if the given plain entity and tone combination is valid.

Only syllables with unreleased finals occur with stop tones, other forms must not (see hasStopTone()).

  • plainEntity (str) – entity without tonal information
  • tone (str) – tone
Return type:



True if given combination is valid, False otherwise


Table Of Contents

Previous topic

JyutpingOperator — Jyutping

Next topic

ShanghaineseIPAOperator — IPA for Shanghainese

This Page