Coverage for src/audioio/audiomarkers.py: 100%

1"""Working with marker lists. 

2 

3Markers are used to mark specific positions or regions in the audio 

4data. Each marker has a position (cue, event), a span, a label, and a 

5text. Position, and span are handled with 1-D or 2-D arrays of ints, 

6where each row is a marker and the columns are position and optional 

7span. Labels and texts come in another 1-D or 2-D array of objects 

8pointing to strings. Again, rows are the markers, first column are the 

9labels, and second column the optional texts. Try to keep the labels 

10short, and use text for longer descriptions. 

11 

12- `write_markers()`: write markers to a text file or stream. 

13- `print_markers()`: write markers to standard output. 

14 

15""" 

16 

17import sys 

18 

19 

20def write_markers(fh, locs, labels=None, sep=' ', prefix=''): 

21 """Write markers to a text file or stream. 

22 

23 Parameters 

24 ---------- 

25 fh: filename or stream 

26 If not a stream, the file with name `fh` is opened. 

27 Otherwise `fh` is used as a stream for writing. 

28 locs: 1-D or 2-D array of ints 

29 Marker positions (first column) and optional spans (second column) 

30 for each marker (rows). 

31 labels: 1-D or 2-D array of string objects 

32 Labels (first column) and optional texts (second column) 

33 for each marker (rows). 

34 sep: str 

35 Column separator. 

36 prefix: str 

37 This string is written at the beginning of each line. 

38 """ 

39 if hasattr(fh, 'write'): 

40 own_file = False 

41 else: 

42 own_file = True 

43 fh = open(fh, 'w') 

44 # what do we have: 

45 if locs.ndim == 1: 

46 locs = locs.reshape(-1, 1) 

47 has_span = locs.shape[1] > 1 

48 has_labels = False 

49 has_text = False 

50 if labels is not None and len(labels) > 0: 

51 has_labels = True 

52 if labels.ndim == 1: 

53 labels = labels.reshape(-1, 1) 

54 has_text = labels.shape[1] > 1 

55 # table header: 

56 fh.write(f'{prefix}{"position":10}') 

57 if has_span: 

58 fh.write(f'{sep}{"span":8}') 

59 if has_labels: 

60 fh.write(f'{sep}{"label":10}') 

61 if has_text: 

62 fh.write(f'{sep}{"text"}') 

63 fh.write('\n') 

64 # table data: 

65 for i in range(len(locs)): 

66 fh.write(f'{prefix}{locs[i,0]:10}') 

67 if has_span: 

68 fh.write(f'{sep}{locs[i,1]:8}') 

69 if has_labels: 

70 fh.write(f'{sep}{labels[i,0]:10}') 

71 if has_text: 

72 fh.write(f'{sep}{labels[i,1]}') 

73 fh.write('\n') 

74 if own_file: 

75 fh.close() 

76 

77 

78def print_markers(locs, labels=None, sep=' ', prefix=''): 

79 """Write markers to standard output. 

80 

81 Parameters 

82 ---------- 

83 locs: 1-D or 2-D array of ints 

84 Marker positions (first column) and optional spans (second column) 

85 for each marker (rows). 

86 labels: 1-D or 2-D array of string objects 

87 Labels (first column) and optional texts (second column) 

88 for each marker (rows). 

89 sep: str 

90 Column separator. 

91 prefix: str 

92 This string is written at the beginning of each line. 

93 """ 

94 write_markers(sys.stdout, locs, labels, sep, prefix) 

95