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 

194from .version import __version__, __year__ 

195 

196 

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

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

199 

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

201 

202 Parameters 

203 ---------- 

204 fh: filename or stream 

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

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

207 meta: nested dict 

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

209 prefix: str 

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

211 indent: int 

212 Number of characters used for indentation of sections. 

213 replace: char or None 

214 If specified, replace special characters by this character. 

215 

216 Examples 

217 -------- 

218 ``` 

219 from audioio import write_metadata 

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

221 write_metadata('info.txt', md) 

222 ``` 

223 """ 

224 

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

226 w = 0 

227 for k in md: 

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

229 w = len(k) 

230 for k in md: 

231 clevel = level*indent 

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

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

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

235 else: 

236 value = md[k] 

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

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

239 else: 

240 value = f'{value}' 

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

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

243 if len(smap) > 0: 

244 value = value.translate(smap) 

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

246 

247 if not meta: 

248 return 

249 if hasattr(fh, 'write'): 

250 own_file = False 

251 else: 

252 own_file = True 

253 fh = open(fh, 'w') 

254 smap = {} 

255 if replace: 

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

257 write_dict(fh, meta, 0, smap) 

258 if own_file: 

259 fh.close() 

260 

261 

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

263 """Write meta data to standard output. 

264 

265 Parameters 

266 ---------- 

267 meta: nested dict 

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

269 prefix: str 

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

271 indent: int 

272 Number of characters used for indentation of sections. 

273 replace: char or None 

274 If specified, replace special characters by this character. 

275 

276 Examples 

277 -------- 

278 ``` 

279 >>> from audioio import print_metadata 

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

281 >>> print_metadata(md) 

282 aaaa: 2 

283 bbbb: 

284 ccc: 3 

285 ddd: 4 

286 eee: 

287 hh: 5 

288 iiii: 

289 jjj: 6 

290 ``` 

291 """ 

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

293 

294 

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

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

297 

298 Parameters 

299 ---------- 

300 md: nested dict 

301 Metadata as returned by `metadata()`. 

302 keep_sections: bool 

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

304 sep: str 

305 String for separating section names. 

306 

307 Returns 

308 ------- 

309 d: dict 

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

311 

312 Examples 

313 -------- 

314 ``` 

315 >>> from audioio import print_metadata, flatten_metadata 

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

317 >>> print_metadata(md) 

318 aaaa: 2 

319 bbbb: 

320 ccc: 3 

321 ddd: 4 

322 eee: 

323 hh: 5 

324 iiii: 

325 jjj: 6 

326  

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

328 >>> print_metadata(fmd) 

329 aaaa : 2 

330 bbbb.ccc : 3 

331 bbbb.ddd : 4 

332 bbbb.eee.hh: 5 

333 iiii.jjj : 6 

334 ``` 

335 """ 

336 def flatten(cd, section): 

337 df = {} 

338 for k in cd: 

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

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

341 else: 

342 if keep_sections: 

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

344 else: 

345 df[k] = cd[k] 

346 return df 

347 

348 return flatten(md, '') 

349 

350 

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

352 """Unflatten a previously flattened metadata dictionary. 

353 

354 Parameters 

355 ---------- 

356 md: dict 

357 Flat dictionary with key-value pairs as obtained from 

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

359 sep: str 

360 String that separates section names. 

361 

362 Returns 

363 ------- 

364 d: nested dict 

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

366 

367 Examples 

368 -------- 

369 ``` 

370 >>> from audioio import print_metadata, unflatten_metadata 

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

372 >>> print_metadata(fmd) 

373 aaaa : 2 

374 bbbb.ccc : 3 

375 bbbb.ddd : 4 

376 bbbb.eee.hh: 5 

377 iiii.jjj : 6 

378  

379 >>> md = unflatten_metadata(fmd) 

380 >>> print_metadata(md) 

381 aaaa: 2 

382 bbbb: 

383 ccc: 3 

384 ddd: 4 

385 eee: 

386 hh: 5 

387 iiii: 

388 jjj: 6 

389 ``` 

390 """ 

391 umd = {} # unflattened metadata 

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

393 csk = [] # current section keys 

394 for k in md: 

395 ks = k.split(sep) 

396 # go up the hierarchy: 

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

398 csk.pop() 

399 cmd.pop() 

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

401 if kss == csk[-1]: 

402 break 

403 csk.pop() 

404 cmd.pop() 

405 # add new sections: 

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

407 csk.append(kss) 

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

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

410 # add key-value pair: 

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

412 return umd 

413 

414 

415def parse_number(s): 

416 """Parse string with number and unit. 

417 

418 Parameters 

419 ---------- 

420 s: str, float, or int 

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

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

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

424 as the value with empty unit. 

425 

426 Returns 

427 ------- 

428 v: None, int, or float 

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

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

431 u: str 

432 Unit that follows the initial number. 

433 n: int 

434 Number of digits behind the decimal point. 

435 

436 Examples 

437 -------- 

438 

439 ``` 

440 >>> from audioio import parse_number 

441 

442 # integer: 

443 >>> parse_number('42') 

444 (42, '', 0) 

445 

446 # integer with unit: 

447 >>> parse_number('42ms') 

448 (42, 'ms', 0) 

449 

450 # float with unit: 

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

452 (42.0, 'ms', 0) 

453 

454 # float with unit: 

455 >>> parse_number('42.3ms') 

456 (42.3, 'ms', 1) 

457 

458 # float with space and unit: 

459 >>> parse_number('423.17 Hz') 

460 (423.17, 'Hz', 2) 

461 ``` 

462 

463 """ 

464 if not isinstance(s, str): 

465 if isinstance(s, int): 

466 return s, '', 0 

467 if isinstance(s, float): 

468 return s, '', 5 

469 else: 

470 return None, '', 0 

471 n = len(s) 

472 ip = n 

473 have_point = False 

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

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

476 if have_point: 

477 n = i 

478 break 

479 have_point = True 

480 ip = i + 1 

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

482 n = i 

483 break 

484 if n == 0: 

485 return None, s, 0 

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

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

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

489 return v, u, nd 

490 

491 

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

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

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

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

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

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

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

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

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

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

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

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

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

505 

506 

507def change_unit(val, old_unit, new_unit): 

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

509 

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

511 

512 Parameters 

513 ---------- 

514 val: float 

515 Value given in `old_unit`. 

516 old_unit: str 

517 Unit of `val`. 

518 new_unit: str 

519 Requested unit of return value. 

520 

521 Returns 

522 ------- 

523 new_val: float 

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

525 

526 Examples 

527 -------- 

528 

529 ``` 

530 >>> from audioio import change_unit 

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

532 0.5 

533 

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

535 5.0 

536 

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

538 5.0 

539 

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

541 50.0 

542 

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

544 4000.0 

545 

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

547 0.12 

548 

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

550 124.0 

551 

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

553 150.0 

554 

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

556 1.0 

557 

558 ``` 

559 

560 """ 

561 # missing unit? 

562 if not old_unit and not new_unit: 

563 return val 

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

565 return val 

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

567 return val 

568 

569 # special units that directly translate into factors: 

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

571 

572 # parse old unit: 

573 f1 = 1.0 

574 if old_unit in unit_factors: 

575 f1 = unit_factors[old_unit] 

576 else: 

577 for k in unit_prefixes: 

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

579 f1 = unit_prefixes[k]; 

580 

581 # parse new unit: 

582 f2 = 1.0 

583 if new_unit in unit_factors: 

584 f2 = unit_factors[new_unit] 

585 else: 

586 for k in unit_prefixes: 

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

588 f2 = unit_prefixes[k]; 

589 

590 return val*f1/f2 

591 

592 

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

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

595 

596 Parameters 

597 ---------- 

598 metadata: nested dict 

599 Metadata. 

600 key: str 

601 Key to be searched for (case insensitive). 

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

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

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

605 sep: str 

606 String that separates section names in `key`. 

607 

608 Returns 

609 ------- 

610 md: dict 

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

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

613 the top-level dictionary is returned. 

614 key: str 

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

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

617 

618 Examples 

619 -------- 

620 

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

622 returned dictionary with the returned key. 

623 

624 ``` 

625 >>> from audioio import print_metadata, find_key 

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

627 >>> print_metadata(md) 

628 aaaa: 2 

629 bbbb: 

630 ccc: 3 

631 ddd: 4 

632 eee: 

633 ff: 5 

634 gggg: 

635 hhh: 6 

636 

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

638 >>> m[k] = 10 

639 >>> print_metadata(md) 

640 aaaa: 2 

641 bbbb: 

642 ccc: 3 

643 ddd: 10 

644 ... 

645 

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

647 >>> m[k] = 12 

648 >>> print_metadata(md) 

649 ... 

650 gggg: 

651 hhh: 12 

652 

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

654 >>> m[k] = 42 

655 >>> print_metadata(md) 

656 ... 

657 eee: 

658 ff: 5 

659 xx: 42 

660 ... 

661 ``` 

662 

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

664 is returned: 

665 ```py 

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

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

668 >>> print_metadata(md) 

669 ... 

670 eee: 

671 ff: 5 

672 xx: 42 

673 yy: 46 

674 ... 

675 ``` 

676 

677 """ 

678 def find_keys(metadata, keys): 

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

680 for k in metadata: 

681 if k.upper() == key: 

682 if len(keys) == 1: 

683 # found key: 

684 return True, metadata, k 

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

686 # keep searching within the next section: 

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

688 # search in subsections: 

689 for k in metadata: 

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

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

692 if found: 

693 return True, mm, kk 

694 # nothing found: 

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

696 

697 if metadata is None: 

698 return {}, None 

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

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

701 return mm, kk 

702 

703 

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

705 default_unit='', remove=False): 

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

707 

708 Parameters 

709 ---------- 

710 metadata: nested dict 

711 Metadata. 

712 keys: str or list of str 

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

714 Value of the first key found is returned. 

715 May contain section names separated by `sep`.  

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

717 sep: str 

718 String that separates section names in `key`. 

719 default: None, int, or float 

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

721 not contain a number. 

722 default_unit: str 

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

724 not have a unit. 

725 remove: bool 

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

727 

728 Returns 

729 ------- 

730 v: None, int, or float 

731 Value referenced by `key` as float. 

732 Without decimal point, an int is returned. 

733 If none of the `keys` was found or 

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

735 then `default` is returned. 

736 u: str 

737 Corresponding unit. 

738 

739 Examples 

740 -------- 

741 

742 ``` 

743 >>> from audioio import get_number_unit 

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

745 

746 # integer: 

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

748 (42, '') 

749 

750 # float with unit: 

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

752 (42.3, 'ms') 

753 

754 # two keys: 

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

756 (42.3, 'ms') 

757 

758 # not found: 

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

760 (None, '') 

761 

762 # not found with default value: 

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

764 (1.0, 'a.u.') 

765 ``` 

766 

767 """ 

768 if not metadata: 

769 return default, default_unit 

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

771 keys = (keys,) 

772 value = default 

773 unit = default_unit 

774 for key in keys: 

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

776 if k in m: 

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

778 if v is not None: 

779 if not u: 

780 u = default_unit 

781 if remove: 

782 del m[k] 

783 return v, u 

784 elif u and unit == default_unit: 

785 unit = u 

786 return value, unit 

787 

788 

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

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

791 

792 Parameters 

793 ---------- 

794 metadata: nested dict 

795 Metadata. 

796 unit: str 

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

798 keys: str or list of str 

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

800 Value of the first key found is returned. 

801 May contain section names separated by `sep`.  

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

803 sep: str 

804 String that separates section names in `key`. 

805 default: None, int, or float 

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

807 not contain a number. 

808 remove: bool 

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

810 

811 Returns 

812 ------- 

813 v: None or float 

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

815 If none of the `keys` was found or 

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

817 then `default` is returned. 

818 

819 Examples 

820 -------- 

821 

822 ``` 

823 >>> from audioio import get_number 

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

825 

826 # milliseconds to seconds: 

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

828 0.0423 

829 

830 # milliseconds to microseconds: 

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

832 42300.0 

833 

834 # value without unit is not scaled: 

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

836 42 

837 

838 # two keys: 

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

840 0.0423 

841 

842 # not found: 

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

844 None 

845 

846 # not found with default value: 

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

848 1.0 

849 ``` 

850 

851 """ 

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

853 if v is None: 

854 return default 

855 else: 

856 return change_unit(v, u, unit) 

857 

858 

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

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

861 

862 Parameters 

863 ---------- 

864 metadata: nested dict 

865 Metadata. 

866 keys: str or list of str 

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

868 Value of the first key found is returned. 

869 May contain section names separated by `sep`.  

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

871 sep: str 

872 String that separates section names in `key`. 

873 default: None or int 

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

875 not contain an integer. 

876 remove: bool 

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

878 

879 Returns 

880 ------- 

881 v: None or int 

882 Value referenced by `key` as integer. 

883 If none of the `keys` was found, 

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

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

886 

887 Examples 

888 -------- 

889 

890 ``` 

891 >>> from audioio import get_int 

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

893 

894 # integer: 

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

896 42 

897 

898 # two keys: 

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

900 42 

901 

902 # float: 

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

904 None 

905 

906 # not found: 

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

908 None 

909 

910 # not found with default value: 

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

912 0 

913 ``` 

914 

915 """ 

916 if not metadata: 

917 return default 

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

919 keys = (keys,) 

920 for key in keys: 

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

922 if k in m: 

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

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

925 if remove: 

926 del m[k] 

927 return int(v) 

928 return default 

929 

930 

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

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

933 

934 Parameters 

935 ---------- 

936 metadata: nested dict 

937 Metadata. 

938 keys: str or list of str 

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

940 Value of the first key found is returned. 

941 May contain section names separated by `sep`.  

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

943 sep: str 

944 String that separates section names in `key`. 

945 default: None or bool 

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

947 not specify a boolean value. 

948 remove: bool 

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

950 

951 Returns 

952 ------- 

953 v: None or bool 

954 Value referenced by `key` as boolean. 

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

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

957 If none of the `keys` was found or 

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

959 then `default` is returned. 

960 

961 Examples 

962 -------- 

963 

964 ``` 

965 >>> from audioio import get_bool 

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

967 

968 # case insensitive: 

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

970 True 

971 

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

973 False 

974 

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

976 False 

977 

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

979 True 

980 

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

982 True 

983 

984 # not found: 

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

986 None 

987 

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

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

990 True 

991 

992 # two keys (take first match): 

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

994 False 

995 

996 # not found with default value: 

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

998 False 

999 ``` 

1000 

1001 """ 

1002 if not metadata: 

1003 return default 

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

1005 keys = (keys,) 

1006 val = default 

1007 mv = None 

1008 kv = None 

1009 for key in keys: 

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

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

1012 vs = m[k] 

1013 v, _, _ = parse_number(vs) 

1014 if v is not None: 

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

1016 mv = m 

1017 kv = k 

1018 elif isinstance(vs, str): 

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

1020 if remove: 

1021 del m[k] 

1022 return True 

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

1024 if remove: 

1025 del m[k] 

1026 return False 

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

1028 del mv[kv] 

1029 return val 

1030 

1031 

1032default_starttime_keys = [['DateTimeOriginal'], 

1033 ['OriginationDate', 'OriginationTime'], 

1034 ['Location_Time'], 

1035 ['Timestamp']] 

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

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

1038""" 

1039 

1040def get_datetime(metadata, keys=default_starttime_keys, 

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

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

1043 

1044 Parameters 

1045 ---------- 

1046 metadata: nested dict 

1047 Metadata. 

1048 keys: tuple of str or list of tuple of str 

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

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

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

1052 tuples with one or two keys. 

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

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

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

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

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

1058 of the `audiometadata` module. 

1059 sep: str 

1060 String that separates section names in `key`. 

1061 default: None or str 

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

1063 not contain a string. 

1064 remove: bool 

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

1066 

1067 Returns 

1068 ------- 

1069 v: None or datetime 

1070 Datetime referenced by `keys`. 

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

1072 

1073 Examples 

1074 -------- 

1075 

1076 ``` 

1077 >>> from audioio import get_datetime 

1078 >>> import datetime as dt 

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

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

1081 

1082 # separate date and time: 

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

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

1085 

1086 # single datetime: