Coverage for src / audioio / audiometadata.py: 99%

1"""Working with metadata. 

2 

3To interface the various ways metadata are stored in audio files, the 

4`audioio` package uses nested dictionaries. The keys are always 

5strings. Values are strings, integers, floats, datetimes, or other 

6types. Value strings can also be numbers followed by a unit, 

7e.g. "4.2mV". For defining subsections of key-value pairs, values can 

8be dictionaries. The dictionaries can be nested to arbitrary depth. 

9 

10```py 

11>>> from audioio import print_metadata 

12>>> md = dict(Recording=dict(Experimenter='John Doe', 

13 DateTimeOriginal='2023-10-01T14:10:02', 

14 Count=42), 

15 Hardware=dict(Amplifier='Teensy_Amp 4.1', 

16 Highpass='10Hz', 

17 Gain='120mV')) 

18>>> print_metadata(md) 

19``` 

20results in 

21```txt 

22Recording: 

23 Experimenter : John Doe 

24 DateTimeOriginal: 2023-10-01T14:10:02 

25 Count : 42 

26Hardware: 

27 Amplifier: Teensy_Amp 4.1 

28 Highpass : 10Hz 

29 Gain : 120mV 

30``` 

31 

32Often, audio files have very specific ways to store metadata. You can 

33enforce using these by putting them into a dictionary that is added to 

34the metadata with a key having the name of the metadata type you want, 

35e.g. the "INFO", "BEXT", "iXML", and "GUAN" chunks of RIFF/WAVE files. 

36 

37## Functions 

38 

39The `audiometadata` module provides functions for handling and 

40manipulating these nested dictionaries. Many functions take keys as 

41arguments for finding or setting specific key-value pairs. These keys 

42can be the key of a specific item of a (sub-) dictionary, no matter on 

43which level of the metadata hierarchy it is. For example, simply 

44searching for "Highpass" retrieves the corrseponding value "10Hz", 

45although "Highpass" is contained in the sub-dictionary (or "section") 

46with key "Hardware". The same item can also be specified together with 

47its parent keys: "Hardware.Highpass". Parent keys (or section keys) 

48are by default separated by '.', but all functions have a `sep` 

49key-word that specifies the string separating section names in 

50keys. Key matching is case insensitive. 

51 

52Since the same items are named by many different keys in the different 

53types of metadata data models, the functions also take lists of keys 

54as arguments. 

55 

56Do not forget that you can easily manipulate the metadata by means of 

57the standard functions of dictionaries. 

58 

59If you need to make a copy of the metadata use `deepcopy`: 

60``` 

61from copy import deepcopy 

62md_orig = deepcopy(md) 

63``` 

64 

65### Output 

66 

67Write nested dictionaries as texts: 

68 

69- `write_metadata_text()`: write meta data into a text/yaml file. 

70- `print_metadata()`: write meta data to standard output. 

71 

72### Flatten 

73 

74Conversion between nested and flat dictionaries: 

75 

76- `flatten_metadata()`: flatten hierachical metadata to a single dictionary. 

77- `unflatten_metadata()`: unflatten a previously flattened metadata dictionary. 

78 

79### Parse numbers with units 

80 

81- `parse_number()`: parse string with number and unit. 

82- `change_unit()`: scale numerical value to a new unit. 

83 

84### Find and get values 

85 

86Find keys and get their values parsed and converted to various types: 

87 

88- `find_key()`: find dictionary in metadata hierarchy containing the specified key. 

89- `get_number_unit()`: find a key in metadata and return its number and unit. 

90- `get_number()`: find a key in metadata and return its value in a given unit. 

91- `get_int()`: find a key in metadata and return its integer value. 

92- `get_bool()`: find a key in metadata and return its boolean value. 

93- `get_datetime()`: find keys in metadata and return a datetime. 

94- `get_str()`: find a key in metadata and return its string value. 

95 

96### Organize metadata 

97 

98Add and remove metadata: 

99 

100- `strlist_to_dict()`: convert list of key-value-pair strings to dictionary. 

101- `add_sections()`: add sections to metadata dictionary. 

102- `set_metadata()`: set values of existing metadata. 

103- `add_metadata()`: add or modify key-value pairs. 

104- `move_metadata()`: remove a key from metadata and add it to a dictionary. 

105- `remove_metadata()`: remove key-value pairs or sections from metadata. 

106- `cleanup_metadata()`: remove empty sections from metadata. 

107 

108### Special metadata fields 

109 

110Retrieve and set specific metadata: 

111 

112- `get_gain()`: get gain and unit from metadata. 

113- `update_gain()`: update gain setting in metadata. 

114- `set_starttime()`: set all start-of-recording times in metadata. 

115- `update_starttime()`: update start-of-recording times in metadata. 

116- `bext_history_str()`: assemble a string for the BEXT CodingHistory field. 

117- `add_history()`: add a string describing coding history to metadata. 

118- `add_unwrap()`: add unwrap infos to metadata. 

119 

120Lists of standard keys: 

121 

122- `default_starttime_keys`: keys of times of start of the recording. 

123- `default_timeref_keys`: keys of integer time references. 

124- `default_gain_keys`: keys of gain settings. 

125- `default_history_keys`: keys of strings describing coding history. 

126 

127 

128## Command line script 

129 

130The module can be run as a script from the command line to display the 

131metadata and markers contained in an audio file: 

132 

133```sh 

134> audiometadata logger.wav 

135``` 

136prints 

137```text 

138file: 

139 filepath : logger.wav 

140 samplingrate: 96000Hz 

141 channels : 16 

142 frames : 17280000 

143 duration : 180.000s 

144 

145metadata: 

146 INFO: 

147 Bits : 32 

148 Pins : 1-CH2R,1-CH2L,1-CH3R,1-CH3L,2-CH2R,2-CH2L,2-CH3R,2-CH3L,3-CH2R,3-CH2L,3-CH3R,3-CH3L,4-CH2R,4-CH2L,4-CH3R,4-CH3L 

149 Gain : 165.00mV 

150 uCBoard : Teensy 4.1 

151 MACAdress : 04:e9:e5:15:3e:95 

152 DateTimeOriginal: 2023-10-01T14:10:02 

153 Software : TeeGrid R4-senors-logger v1.0 

154``` 

155 

156 

157Alternatively, the script can be run from within the audioio source tree as: 

158``` 

159python -m src.audioio.audiometadata audiofile.wav 

160``` 

161 

162Running 

163```sh 

164audiometadata --help 

165``` 

166prints 

167```text 

168usage: audiometadata [-h] [--version] [-f] [-m] [-c] [-t] files [files ...] 

169 

170Convert audio file formats. 

171 

172positional arguments: 

173 files audio file 

174 

175options: 

176 -h, --help show this help message and exit 

177 --version show program's version number and exit 

178 -f list file format only 

179 -m list metadata only 

180 -c list cues/markers only 

181 -t list tags of all riff/wave chunks contained in the file 

182 

183version 2.0.0 by Benda-Lab (2020-2024) 

184``` 

185 

186""" 

187 

188import os 

189import sys 

190import glob 

191import argparse 

192import numpy as np 

193import datetime as dt 

194 

195from .version import __version__, __year__ 

196 

197 

198def write_metadata_text(fh, meta, prefix='', indent=4, replace=None): 

199 """Write meta data into a text/yaml file or stream. 

200 

201 With the default parameters, the output is a valid yaml file. 

202 

203 Parameters 

204 ---------- 

205 fh: filename or stream 

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

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

208 meta: nested dict 

209 Key-value pairs of metadata to be written into the file. 

210 prefix: str 

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

212 indent: int 

213 Number of characters used for indentation of sections. 

214 replace: char or None 

215 If specified, replace special characters by this character. 

216 

217 Examples 

218 -------- 

219 ``` 

220 from audioio import write_metadata 

221 md = dict(aaaa=2, bbbb=dict(ccc=3, ddd=4, eee=dict(hh=5))) 

222 write_metadata('info.txt', md) 

223 ``` 

224 """ 

225 

226 def write_dict(df, md, level, smap): 

227 w = 0 

228 for k in md: 

229 if not isinstance(md[k], dict) and w < len(k): 

230 w = len(k) 

231 for k in md: 

232 clevel = level*indent 

233 if isinstance(md[k], dict): 

234 df.write(f'{prefix}{"":>{clevel}}{k}:\n') 

235 write_dict(df, md[k], level+1, smap) 

236 else: 

237 value = md[k] 

238 if isinstance(value, (list, tuple)): 

239 value = ', '.join([f'{v}' for v in value]) 

240 else: 

241 value = f'{value}' 

242 value = value.replace('\r\n', r'\n') 

243 value = value.replace('\n', r'\n') 

244 if len(smap) > 0: 

245 value = value.translate(smap) 

246 df.write(f'{prefix}{"":>{clevel}}{k:<{w}}: {value}\n') 

247 

248 if not meta: 

249 return 

250 if hasattr(fh, 'write'): 

251 own_file = False 

252 else: 

253 own_file = True 

254 fh = open(fh, 'w') 

255 smap = {} 

256 if replace: 

257 smap = str.maketrans('\r\n\t\x00', ''.join([replace]*4)) 

258 write_dict(fh, meta, 0, smap) 

259 if own_file: 

260 fh.close() 

261 

262 

263def print_metadata(meta, prefix='', indent=4, replace=None): 

264 """Write meta data to standard output. 

265 

266 Parameters 

267 ---------- 

268 meta: nested dict 

269 Key-value pairs of metadata to be written into the file. 

270 prefix: str 

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

272 indent: int 

273 Number of characters used for indentation of sections. 

274 replace: char or None 

275 If specified, replace special characters by this character. 

276 

277 Examples 

278 -------- 

279 ``` 

280 >>> from audioio import print_metadata 

281 >>> md = dict(aaaa=2, bbbb=dict(ccc=3, ddd=4, eee=dict(hh=5)), iiii=dict(jjj=6)) 

282 >>> print_metadata(md) 

283 aaaa: 2 

284 bbbb: 

285 ccc: 3 

286 ddd: 4 

287 eee: 

288 hh: 5 

289 iiii: 

290 jjj: 6 

291 ``` 

292 """ 

293 write_metadata_text(sys.stdout, meta, prefix, indent, replace) 

294 

295 

296def flatten_metadata(md, keep_sections=False, sep='.'): 

297 """Flatten hierarchical metadata to a single dictionary. 

298 

299 Parameters 

300 ---------- 

301 md: nested dict 

302 Metadata as returned by `metadata()`. 

303 keep_sections: bool 

304 If `True`, then prefix keys with section names, separated by `sep`. 

305 sep: str 

306 String for separating section names. 

307 

308 Returns 

309 ------- 

310 d: dict 

311 Non-nested dict containing all key-value pairs of `md`. 

312 

313 Examples 

314 -------- 

315 ``` 

316 >>> from audioio import print_metadata, flatten_metadata 

317 >>> md = dict(aaaa=2, bbbb=dict(ccc=3, ddd=4, eee=dict(hh=5)), iiii=dict(jjj=6)) 

318 >>> print_metadata(md) 

319 aaaa: 2 

320 bbbb: 

321 ccc: 3 

322 ddd: 4 

323 eee: 

324 hh: 5 

325 iiii: 

326 jjj: 6 

327  

328 >>> fmd = flatten_metadata(md, keep_sections=True) 

329 >>> print_metadata(fmd) 

330 aaaa : 2 

331 bbbb.ccc : 3 

332 bbbb.ddd : 4 

333 bbbb.eee.hh: 5 

334 iiii.jjj : 6 

335 ``` 

336 """ 

337 def flatten(cd, section): 

338 df = {} 

339 for k in cd: 

340 if isinstance(cd[k], dict): 

341 df.update(flatten(cd[k], section + k + sep)) 

342 else: 

343 if keep_sections: 

344 df[section+k] = cd[k] 

345 else: 

346 df[k] = cd[k] 

347 return df 

348 

349 return flatten(md, '') 

350 

351 

352def unflatten_metadata(md, sep='.'): 

353 """Unflatten a previously flattened metadata dictionary. 

354 

355 Parameters 

356 ---------- 

357 md: dict 

358 Flat dictionary with key-value pairs as obtained from 

359 `flatten_metadata()` with `keep_sections=True`. 

360 sep: str 

361 String that separates section names. 

362 

363 Returns 

364 ------- 

365 d: nested dict 

366 Hierarchical dictionary with sub-dictionaries and key-value pairs. 

367 

368 Examples 

369 -------- 

370 ``` 

371 >>> from audioio import print_metadata, unflatten_metadata 

372 >>> fmd = {'aaaa': 2, 'bbbb.ccc': 3, 'bbbb.ddd': 4, 'bbbb.eee.hh': 5, 'iiii.jjj': 6} 

373 >>> print_metadata(fmd) 

374 aaaa : 2 

375 bbbb.ccc : 3 

376 bbbb.ddd : 4 

377 bbbb.eee.hh: 5 

378 iiii.jjj : 6 

379  

380 >>> md = unflatten_metadata(fmd) 

381 >>> print_metadata(md) 

382 aaaa: 2 

383 bbbb: 

384 ccc: 3 

385 ddd: 4 

386 eee: 

387 hh: 5 

388 iiii: 

389 jjj: 6 

390 ``` 

391 """ 

392 umd = {} # unflattened metadata 

393 cmd = [umd] # current metadata dicts for each level of the hierarchy 

394 csk = [] # current section keys 

395 for k in md: 

396 ks = k.split(sep) 

397 # go up the hierarchy: 

398 for i in range(len(csk) - len(ks)): 

399 csk.pop() 

400 cmd.pop() 

401 for kss in reversed(ks[:len(csk)]): 

402 if kss == csk[-1]: 

403 break 

404 csk.pop() 

405 cmd.pop() 

406 # add new sections: 

407 for kss in ks[len(csk):-1]: 

408 csk.append(kss) 

409 cmd[-1][kss] = {} 

410 cmd.append(cmd[-1][kss]) 

411 # add key-value pair: 

412 cmd[-1][ks[-1]] = md[k] 

413 return umd 

414 

415 

416def parse_number(s): 

417 """Parse string with number and unit. 

418 

419 Parameters 

420 ---------- 

421 s: str, float, or int 

422 String to be parsed. The initial part of the string is 

423 expected to be a number, the part following the number is 

424 interpreted as the unit. If float or int, then return this 

425 as the value with empty unit. 

426 

427 Returns 

428 ------- 

429 v: None, int, or float 

430 Value of the string as float. Without decimal point, an int is returned. 

431 If the string does not contain a number, None is returned. 

432 u: str 

433 Unit that follows the initial number. 

434 n: int 

435 Number of digits behind the decimal point. 

436 

437 Examples 

438 -------- 

439 

440 ``` 

441 >>> from audioio import parse_number 

442 

443 # integer: 

444 >>> parse_number('42') 

445 (42, '', 0) 

446 

447 # integer with unit: 

448 >>> parse_number('42ms') 

449 (42, 'ms', 0) 

450 

451 # float with unit: 

452 >>> parse_number('42.ms') 

453 (42.0, 'ms', 0) 

454 

455 # float with unit: 

456 >>> parse_number('42.3ms') 

457 (42.3, 'ms', 1) 

458 

459 # float with space and unit: 

460 >>> parse_number('423.17 Hz') 

461 (423.17, 'Hz', 2) 

462 ``` 

463 

464 """ 

465 if not isinstance(s, str): 

466 if isinstance(s, int): 

467 return s, '', 0 

468 if isinstance(s, float): 

469 return s, '', 5 

470 else: 

471 return None, '', 0 

472 n = len(s) 

473 ip = n 

474 have_point = False 

475 for i in range(len(s)): 

476 if s[i] == '.': 

477 if have_point: 

478 n = i 

479 break 

480 have_point = True 

481 ip = i + 1 

482 if not s[i] in '0123456789.+-': 

483 n = i 

484 break 

485 if n == 0: 

486 return None, s, 0 

487 v = float(s[:n]) if have_point else int(s[:n]) 

488 u = s[n:].strip() 

489 nd = n - ip if n >= ip else 0 

490 return v, u, nd 

491 

492 

493unit_prefixes = {'Deka': 1e1, 'deka': 1e1, 'Hekto': 1e2, 'hekto': 1e2, 

494 'kilo': 1e3, 'Kilo': 1e3, 'Mega': 1e6, 'mega': 1e6, 

495 'Giga': 1e9, 'giga': 1e9, 'Tera': 1e12, 'tera': 1e12, 

496 'Peta': 1e15, 'peta': 1e15, 'Exa': 1e18, 'exa': 1e18, 

497 'Dezi': 1e-1, 'dezi': 1e-1, 'Zenti': 1e-2, 'centi': 1e-2, 

498 'Milli': 1e-3, 'milli': 1e-3, 'Micro': 1e-6, 'micro': 1e-6, 

499 'Nano': 1e-9, 'nano': 1e-9, 'Piko': 1e-12, 'piko': 1e-12, 

500 'Femto': 1e-15, 'femto': 1e-15, 'Atto': 1e-18, 'atto': 1e-18, 

501 'da': 1e1, 'h': 1e2, 'K': 1e3, 'k': 1e3, 'M': 1e6, 

502 'G': 1e9, 'T': 1e12, 'P': 1e15, 'E': 1e18, 

503 'd': 1e-1, 'c': 1e-2, 'mu': 1e-6, 'u': 1e-6, 'm': 1e-3, 

504 'n': 1e-9, 'p': 1e-12, 'f': 1e-15, 'a': 1e-18} 

505""" SI prefixes for units with corresponding factors. """ 

506 

507 

508def change_unit(val, old_unit, new_unit): 

509 """Scale numerical value to a new unit. 

510 

511 Adapted from https://github.com/relacs/relacs/blob/1facade622a80e9f51dbf8e6f8171ac74c27f100/options/src/parameter.cc#L1647-L1703 

512 

513 Parameters 

514 ---------- 

515 val: float 

516 Value given in `old_unit`. 

517 old_unit: str 

518 Unit of `val`. 

519 new_unit: str 

520 Requested unit of return value. 

521 

522 Returns 

523 ------- 

524 new_val: float 

525 The input value `val` scaled to `new_unit`. 

526 

527 Examples 

528 -------- 

529 

530 ``` 

531 >>> from audioio import change_unit 

532 >>> change_unit(5, 'mm', 'cm') 

533 0.5 

534 

535 >>> change_unit(5, '', 'cm') 

536 5.0 

537 

538 >>> change_unit(5, 'mm', '') 

539 5.0 

540 

541 >>> change_unit(5, 'cm', 'mm') 

542 50.0 

543 

544 >>> change_unit(4, 'kg', 'g') 

545 4000.0 

546 

547 >>> change_unit(12, '%', '') 

548 0.12 

549 

550 >>> change_unit(1.24, '', '%') 

551 124.0 

552 

553 >>> change_unit(2.5, 'min', 's') 

554 150.0 

555 

556 >>> change_unit(3600, 's', 'h') 

557 1.0 

558 

559 ``` 

560 

561 """ 

562 # missing unit? 

563 if not old_unit and not new_unit: 

564 return val 

565 if not old_unit and new_unit != '%': 

566 return val 

567 if not new_unit and old_unit != '%': 

568 return val 

569 

570 # special units that directly translate into factors: 

571 unit_factors = {'%': 0.01, 'hour': 60.0*60.0, 'h': 60.0*60.0, 'min': 60.0} 

572 

573 # parse old unit: 

574 f1 = 1.0 

575 if old_unit in unit_factors: 

576 f1 = unit_factors[old_unit] 

577 else: 

578 for k in unit_prefixes: 

579 if len(old_unit) > len(k) and old_unit[:len(k)] == k: 

580 f1 = unit_prefixes[k]; 

581 

582 # parse new unit: 

583 f2 = 1.0 

584 if new_unit in unit_factors: 

585 f2 = unit_factors[new_unit] 

586 else: 

587 for k in unit_prefixes: 

588 if len(new_unit) > len(k) and new_unit[:len(k)] == k: 

589 f2 = unit_prefixes[k]; 

590 

591 return val*f1/f2 

592 

593 

594def find_key(metadata, key, sep='.'): 

595 """Find dictionary in metadata hierarchy containing the specified key. 

596 

597 Parameters 

598 ---------- 

599 metadata: nested dict 

600 Metadata. 

601 key: str 

602 Key to be searched for (case insensitive). 

603 May contain section names separated by `sep`, i.e. 

604 "aaa.bbb.ccc" searches "ccc" (can be key-value pair or section) 

605 in section "bbb" that needs to be a subsection of section "aaa". 

606 sep: str 

607 String that separates section names in `key`. 

608 

609 Returns 

610 ------- 

611 md: dict 

612 The innermost dictionary matching some sections of the search key. 

613 If `key` is not at all contained in the metadata, 

614 the top-level dictionary is returned. 

615 key: str 

616 The part of the search key that was not found in `md`, or the 

617 the final part of the search key, found in `md`. 

618 

619 Examples 

620 -------- 

621 

622 Independent of whether found or not found, you can assign to the 

623 returned dictionary with the returned key. 

624 

625 ``` 

626 >>> from audioio import print_metadata, find_key 

627 >>> md = dict(aaaa=2, bbbb=dict(ccc=3, ddd=4, eee=dict(ff=5)), gggg=dict(hhh=6)) 

628 >>> print_metadata(md) 

629 aaaa: 2 

630 bbbb: 

631 ccc: 3 

632 ddd: 4 

633 eee: 

634 ff: 5 

635 gggg: 

636 hhh: 6 

637 

638 >>> m, k = find_key(md, 'bbbb.ddd') 

639 >>> m[k] = 10 

640 >>> print_metadata(md) 

641 aaaa: 2 

642 bbbb: 

643 ccc: 3 

644 ddd: 10 

645 ... 

646 

647 >>> m, k = find_key(md, 'hhh') 

648 >>> m[k] = 12 

649 >>> print_metadata(md) 

650 ... 

651 gggg: 

652 hhh: 12 

653 

654 >>> m, k = find_key(md, 'bbbb.eee.xx') 

655 >>> m[k] = 42 

656 >>> print_metadata(md) 

657 ... 

658 eee: 

659 ff: 5 

660 xx: 42 

661 ... 

662 ``` 

663 

664 When searching for sections, the one conaining the searched section 

665 is returned: 

666 ```py 

667 >>> m, k = find_key(md, 'eee') 

668 >>> m[k]['yy'] = 46 

669 >>> print_metadata(md) 

670 ... 

671 eee: 

672 ff: 5 

673 xx: 42 

674 yy: 46 

675 ... 

676 ``` 

677 

678 """ 

679 def find_keys(metadata, keys): 

680 key = keys[0].strip().upper() 

681 for k in metadata: 

682 if k.upper() == key: 

683 if len(keys) == 1: 

684 # found key: 

685 return True, metadata, k 

686 elif isinstance(metadata[k], dict): 

687 # keep searching within the next section: 

688 return find_keys(metadata[k], keys[1:]) 

689 # search in subsections: 

690 for k in metadata: 

691 if isinstance(metadata[k], dict): 

692 found, mm, kk = find_keys(metadata[k], keys) 

693 if found: 

694 return True, mm, kk 

695 # nothing found: 

696 return False, metadata, sep.join(keys) 

697 

698 if metadata is None: 

699 return {}, None 

700 ks = key.strip().split(sep) 

701 found, mm, kk = find_keys(metadata, ks) 

702 return mm, kk 

703 

704 

705def get_number_unit(metadata, keys, sep='.', default=None, 

706 default_unit='', remove=False): 

707 """Find a key in metadata and return its number and unit. 

708 

709 Parameters 

710 ---------- 

711 metadata: nested dict 

712 Metadata. 

713 keys: str or list of str 

714 Keys in the metadata to be searched for (case insensitive). 

715 Value of the first key found is returned. 

716 May contain section names separated by `sep`.  

717 See `audiometadata.find_key()` for details. 

718 sep: str 

719 String that separates section names in `key`. 

720 default: None, int, or float 

721 Returned value if `key` is not found or the value does 

722 not contain a number. 

723 default_unit: str 

724 Returned unit if `key` is not found or the key's value does 

725 not have a unit. 

726 remove: bool 

727 If `True`, remove the found key from `metadata`. 

728 

729 Returns 

730 ------- 

731 v: None, int, or float 

732 Value referenced by `key` as float. 

733 Without decimal point, an int is returned. 

734 If none of the `keys` was found or 

735 the key`s value does not contain a number, 

736 then `default` is returned. 

737 u: str 

738 Corresponding unit. 

739 

740 Examples 

741 -------- 

742 

743 ``` 

744 >>> from audioio import get_number_unit 

745 >>> md = dict(aaaa='42', bbbb='42.3ms') 

746 

747 # integer: 

748 >>> get_number_unit(md, 'aaaa') 

749 (42, '') 

750 

751 # float with unit: 

752 >>> get_number_unit(md, 'bbbb') 

753 (42.3, 'ms') 

754 

755 # two keys: 

756 >>> get_number_unit(md, ['cccc', 'bbbb']) 

757 (42.3, 'ms') 

758 

759 # not found: 

760 >>> get_number_unit(md, 'cccc') 

761 (None, '') 

762 

763 # not found with default value: 

764 >>> get_number_unit(md, 'cccc', default=1.0, default_unit='a.u.') 

765 (1.0, 'a.u.') 

766 ``` 

767 

768 """ 

769 if not metadata: 

770 return default, default_unit 

771 if not isinstance(keys, (list, tuple, np.ndarray)): 

772 keys = (keys,) 

773 value = default 

774 unit = default_unit 

775 for key in keys: 

776 m, k = find_key(metadata, key, sep) 

777 if k in m: 

778 v, u, _ = parse_number(m[k]) 

779 if v is not None: 

780 if not u: 

781 u = default_unit 

782 if remove: 

783 del m[k] 

784 return v, u 

785 elif u and unit == default_unit: 

786 unit = u 

787 return value, unit 

788 

789 

790def get_number(metadata, unit, keys, sep='.', default=None, remove=False): 

791 """Find a key in metadata and return its value in a given unit. 

792 

793 Parameters 

794 ---------- 

795 metadata: nested dict 

796 Metadata. 

797 unit: str 

798 Unit in which to return numerical value referenced by one of the `keys`. 

799 keys: str or list of str 

800 Keys in the metadata to be searched for (case insensitive). 

801 Value of the first key found is returned. 

802 May contain section names separated by `sep`.  

803 See `audiometadata.find_key()` for details. 

804 sep: str 

805 String that separates section names in `key`. 

806 default: None, int, or float 

807 Returned value if `key` is not found or the value does 

808 not contain a number. 

809 remove: bool 

810 If `True`, remove the found key from `metadata`. 

811 

812 Returns 

813 ------- 

814 v: None or float 

815 Value referenced by `key` as float scaled to `unit`. 

816 If none of the `keys` was found or 

817 the key`s value does not contain a number, 

818 then `default` is returned. 

819 

820 Examples 

821 -------- 

822 

823 ``` 

824 >>> from audioio import get_number 

825 >>> md = dict(aaaa='42', bbbb='42.3ms') 

826 

827 # milliseconds to seconds: 

828 >>> get_number(md, 's', 'bbbb') 

829 0.0423 

830 

831 # milliseconds to microseconds: 

832 >>> get_number(md, 'us', 'bbbb') 

833 42300.0 

834 

835 # value without unit is not scaled: 

836 >>> get_number(md, 'Hz', 'aaaa') 

837 42 

838 

839 # two keys: 

840 >>> get_number(md, 's', ['cccc', 'bbbb']) 

841 0.0423 

842 

843 # not found: 

844 >>> get_number(md, 's', 'cccc') 

845 None 

846 

847 # not found with default value: 

848 >>> get_number(md, 's', 'cccc', default=1.0) 

849 1.0 

850 ``` 

851 

852 """ 

853 v, u = get_number_unit(metadata, keys, sep, None, unit, remove) 

854 if v is None: 

855 return default 

856 else: 

857 return change_unit(v, u, unit) 

858 

859 

860def get_int(metadata, keys, sep='.', default=None, remove=False): 

861 """Find a key in metadata and return its integer value. 

862 

863 Parameters 

864 ---------- 

865 metadata: nested dict 

866 Metadata. 

867 keys: str or list of str 

868 Keys in the metadata to be searched for (case insensitive). 

869 Value of the first key found is returned. 

870 May contain section names separated by `sep`.  

871 See `audiometadata.find_key()` for details. 

872 sep: str 

873 String that separates section names in `key`. 

874 default: None or int 

875 Return value if `key` is not found or the value does 

876 not contain an integer. 

877 remove: bool 

878 If `True`, remove the found key from `metadata`. 

879 

880 Returns 

881 ------- 

882 v: None or int 

883 Value referenced by `key` as integer. 

884 If none of the `keys` was found, 

885 the key's value does not contain a number or represents 

886 a floating point value, then `default` is returned. 

887 

888 Examples 

889 -------- 

890 

891 ``` 

892 >>> from audioio import get_int 

893 >>> md = dict(aaaa='42', bbbb='42.3ms') 

894 

895 # integer: 

896 >>> get_int(md, 'aaaa') 

897 42 

898 

899 # two keys: 

900 >>> get_int(md, ['cccc', 'aaaa']) 

901 42 

902 

903 # float: 

904 >>> get_int(md, 'bbbb') 

905 None 

906 

907 # not found: 

908 >>> get_int(md, 'cccc') 

909 None 

910 

911 # not found with default value: 

912 >>> get_int(md, 'cccc', default=0) 

913 0 

914 ``` 

915 

916 """ 

917 if not metadata: 

918 return default 

919 if not isinstance(keys, (list, tuple, np.ndarray)): 

920 keys = (keys,) 

921 for key in keys: 

922 m, k = find_key(metadata, key, sep) 

923 if k in m: 

924 v, _, n = parse_number(m[k]) 

925 if v is not None and n == 0: 

926 if remove: 

927 del m[k] 

928 return int(v) 

929 return default 

930 

931 

932def get_bool(metadata, keys, sep='.', default=None, remove=False): 

933 """Find a key in metadata and return its boolean value. 

934 

935 Parameters 

936 ---------- 

937 metadata: nested dict 

938 Metadata. 

939 keys: str or list of str 

940 Keys in the metadata to be searched for (case insensitive). 

941 Value of the first key found is returned. 

942 May contain section names separated by `sep`.  

943 See `audiometadata.find_key()` for details. 

944 sep: str 

945 String that separates section names in `key`. 

946 default: None or bool 

947 Return value if `key` is not found or the value does 

948 not specify a boolean value. 

949 remove: bool 

950 If `True`, remove the found key from `metadata`. 

951 

952 Returns 

953 ------- 

954 v: None or bool 

955 Value referenced by `key` as boolean. 

956 True if 'true', 'yes' (case insensitive) or any number larger than zero. 

957 False if 'false', 'no' (case insensitive) or any number equal to zero. 

958 If none of the `keys` was found or 

959 the key's value does specify a boolean value, 

960 then `default` is returned. 

961 

962 Examples 

963 -------- 

964 

965 ``` 

966 >>> from audioio import get_bool 

967 >>> md = dict(aaaa='TruE', bbbb='No', cccc=0, dddd=1, eeee=True, ffff='ui') 

968 

969 # case insensitive: 

970 >>> get_bool(md, 'aaaa') 

971 True 

972 

973 >>> get_bool(md, 'bbbb') 

974 False 

975 

976 >>> get_bool(md, 'cccc') 

977 False 

978 

979 >>> get_bool(md, 'dddd') 

980 True 

981 

982 >>> get_bool(md, 'eeee') 

983 True 

984 

985 # not found: 

986 >>> get_bool(md, 'ffff') 

987 None 

988 

989 # two keys (string is preferred over number): 

990 >>> get_bool(md, ['cccc', 'aaaa']) 

991 True 

992 

993 # two keys (take first match): 

994 >>> get_bool(md, ['cccc', 'ffff']) 

995 False 

996 

997 # not found with default value: 

998 >>> get_bool(md, 'ffff', default=False) 

999 False 

1000 ``` 

1001 

1002 """ 

1003 if not metadata: 

1004 return default 

1005 if not isinstance(keys, (list, tuple, np.ndarray)): 

1006 keys = (keys,) 

1007 val = default 

1008 mv = None 

1009 kv = None 

1010 for key in keys: 

1011 m, k = find_key(metadata, key, sep) 

1012 if k in m and not isinstance(m[k], dict): 

1013 vs = m[k] 

1014 v, _, _ = parse_number(vs) 

1015 if v is not None: 

1016 val = abs(v) > 1e-8 

1017 mv = m 

1018 kv = k 

1019 elif isinstance(vs, str): 

1020 if vs.upper() in ['TRUE', 'T', 'YES', 'Y']: 

1021 if remove: 

1022 del m[k] 

1023 return True 

1024 if vs.upper() in ['FALSE', 'F', 'NO', 'N']: 

1025 if remove: 

1026 del m[k] 

1027 return False 

1028 if not mv is None and not kv is None and remove: 

1029 del mv[kv] 

1030 return val 

1031 

1032 

1033default_starttime_keys = [['DateTimeOriginal'], 

1034 ['OriginationDate', 'OriginationTime'], 

1035 ['Location_Time'], 

1036 ['Timestamp']] 

1037"""Default keys of times of start of the recording in metadata. 

1038Used by `get_datetime()` and `update_starttime()` functions. 

1039""" 

1040 

1041def get_datetime(metadata, keys=default_starttime_keys, 

1042 sep='.', default=None, remove=False): 

1043 """Find keys in metadata and return a datetime. 

1044 

1045 Parameters 

1046 ---------- 

1047 metadata: nested dict 

1048 Metadata. 

1049 keys: tuple of str or list of tuple of str 

1050 Datetimes can be stored in metadata as two separate key-value pairs, 

1051 one for the date and one for the time. Or by a single key-value pair 

1052 for a date-time value. This is why the keys need to be specified in 

1053 tuples with one or two keys. 

1054 The value of the first tuple of keys found is returned. 

1055 Keys may contain section names separated by `sep`.  

1056 See `audiometadata.find_key()` for details. 

1057 The default values for the `keys` find the start time of a recording. 

1058 You can modify the default keys via the `default_starttime_keys` list 

1059 of the `audiometadata` module. 

1060 sep: str 

1061 String that separates section names in `key`. 

1062 default: None or str 

1063 Return value if `key` is not found or the value does 

1064 not contain a string. 

1065 remove: bool 

1066 If `True`, remove the found key from `metadata`. 

1067 

1068 Returns 

1069 ------- 

1070 v: None or datetime 

1071 Datetime referenced by `keys`. 

1072 If none of the `keys` was found, then `default` is returned. 

1073 

1074 Examples 

1075 -------- 

1076 

1077 ``` 

1078 >>> from audioio import get_datetime 

1079 >>> import datetime as dt 

1080 >>> md = dict(date='2024-03-02', time='10:42:24', 

1081 datetime='2023-04-15T22:10:00') 

1082 

1083 # separate date and time: 

1084 >>> get_datetime(md, ('date', 'time')) 

1085 datetime.datetime(2024, 3, 2, 10, 42, 24) 

1086