Using Apple’s built-in audio conversion and diagnostics

Using Apple’s built-in audio conversion and diagnostics

Apple has included several useful command-line programs for audio engineers and programers which are, unfortunately, not well documented. Among these are utilities for checking for clipping, gathering general playback information, and format conversion utilities. While there are some equivalent 3rd party apps that do the job (OceanAudio, Audacity, etc) it is nice to have a fallback and/or something to tie into when coding an audio program.

-Checking a file for clipping: afclip
This one is simple. In the terminal, type afclip, and then drag your file into the window:

afclip [in file]

The program will scan the file for clipped samples, list any found, and give you a total clipped-sample count. This program checks for inter-sample clipping as well, which is very useful, and often a feature only included in more expensive metering plugins/programs.

The list can be QUITE long if the file is badly clipping, but if there are no clipped samples found, you will get a simple message with the file format data, and a message stating “– no samples clipped —“.  This is an afclip check of a file that I mastered and meticulously checked for clipped samples in several mastering programs (I am relieved to see that afclip approves):


A clipped file will look like this (an audio file extracted from the Movie ‘Terminator’:


The information is formatted as follows (from Apple’s Masteres for iTunes guide):
• Seconds. The time, in seconds, where the clipping occurs. • Sample. The sample number that was clipped. • Channel. The channel of the clipped sample. A value of 0 means the clipping occurred on the left channel, while a value of 1 means the clipping occurred on the right channel. • Value. The raw value of the clipped sample. Since clipping happens when a value exceeds the range of -1 through 1, these values will be below -1 or above 1. • Decibels. The number of decibels by which the sample exceeds the clipping point.
-Gathering audio playback information: afinfo

Prints playback information in the terminal window. The -b option toggles basic info, formatted on a single line (format, channels, sample-rate, bit-rate):


If you converted the file with soundcheck data, you will get loudness information as well:


-Convert file: afconvert

afconvert has the most expansive and complicated options, but it is particularly useful. I recommend typing afconvert -h into the terminal to see the complete list of options (I will paste that output below this blog post as well), but the basic usage is:

afconvert [option] [src_audiofile] [dest_audiofile]

So to convert to data type 24-bit 193kHz (-d LEI24@192000) to file-format .wav (-f WAVE) using the highest-quality samplerate converter complicity (–src-complexity bats) using the highest codec-quality (-q 127) while adding soundcheck loudness data (—soundcheck-generate) use:

afconvert -d LEI24@192000 -f WAVE –src-complexity bats -q 127 [src_audiofile] [dest_audiofile]

Or to convert from ‘wave’ to apple intermediate ‘caff’ while adding soundcheck data but NOT changing the data type (-d 0) use:

afconvert [src_audiofile] [dest_audiofile] -d 0 -f caff — soundcheck-generate

And one more example: Apple’s commands to convert to iTunes Plus AAC:

afconvert [src_audiofile] -d aac -f m4af -u pgcm 2 — soundcheck-read -b 256000 -q 127 -s 2 [dest_audiofile.m4a]

Here is the help file for afconvert:

Audio File Convert
Version: 2.0
Copyright 2003-2013, Apple Inc. All Rights Reserved.
Specify -h (-help) for command options

afconvert [option…] input_file [output_file]
Options may appear before or after the direct arguments. If output_file
is not specified, a name is generated programmatically and the file
is written into the same directory as input_file.
afconvert input_file [-o output_file [option…]]…
Output file options apply to the previous output_file. Other options
may appear anywhere.

General options:
{ -d | –data } data_format[@sample_rate][/format_flags][#frames_per_packet]
[-][BE|LE]{F|[U]I}{8|16|24|32|64} (PCM)
e.g. BEI16 F32@44100
or a data format appropriate to file format (see -hf)
format_flags: hex digits, e.g. ’80’
Frames per packet can be specified for some encoders, e.g.: samr#12
A format of “0” specifies the same format as the source file,
with packets copied exactly.
A format of “N” specifies the destination format should be the
native format of the lossless encoded source file (alac, FLAC only)
{ -c | –channels } number_of_channels
add/remove channels without regard to order
{ -l | –channellayout } layout_tag
layout_tag: name of a constant from CoreAudioTypes.h
(prefix “kAudioChannelLayoutTag_” may be omitted)
if specified once, applies to output file; if twice, the first
applies to the input file, the second to the output file
{ -b | –bitrate } total_bit_rate_bps
e.g. 256000 will give you roughly:
for stereo source: 128000 bits per channel
for 5.1 source: 51000 bits per channel
(the .1 channel consumes few bits and can be discounted in the
total bit rate calculation)
{ -q | –quality } codec_quality
codec_quality: 0-127
{ -r | –src-quality } src_quality
src_quality (sample rate converter quality): 0-127 (default is 127)
{ –src-complexity } src_complexity
src_complexity (sample rate converter complexity): line, norm, bats
{ -s | –strategy } strategy
bitrate allocation strategy for encoding an audio track
0 for CBR, 1 for ABR, 2 for VBR_constrained, 3 for VBR
–prime-method method
decode priming method (see AudioConverter.h)
–prime-override samples_prime samples_remain
can be used to override the priming information stored in the source
file to the specified values. If -1 is specified for either, the value
in the file is used.
don’t page-align audio data in the output file
analyze audio, add SoundCheck data to the output file
–media-kind “media kind string”
media kinds are: “Audio Ad”, “Video Ad”
set a single precision floating point value to
indicate the anchor loudness of the content in dB
generate an SHA-1 hash of the input audio data and add it to the output file.
–codec-manuf codec_manuf
specify the codec with the specified 4-character component manufacturer
–dither algorithm
algorithm: 1-2
enable channel downmixing
{ -u | –userproperty } property value
set an arbitrary AudioConverter property to a given value
property is a four-character code; value can be a signed
32-bit integer or a single precision floating point value.
e.g. ‘-u vbrq <sound_quality>’ sets the sound quality level
(<sound_quality>: 0-127)
May not be used in a transcoding situation.
-ud property value
identical to -u except only applies to a decoder. Fails if there is no
-ue property value
identical to -u except only applies to an encoder. Fails if there is no

Input file options:
–read-track track_index
For input files containing multiple tracks, the index (0..n-1)
of the track to read and convert.
–offset number_of_frames
the starting offset in the input file in frames. (The first frame is
frame zero.)
read SoundCheck data from source file and set it on any destination
file(s) of appropriate filetype (.m4a, .caf).
copy an SHA-1 hash chunk, if present, from the source file to the output file.
–gapless-before filename
file coming before the current input file of a gapless album
–gapless-after filename
file coming after the current input file of a gapless album

Output file options:
-o filename
specify an (additional) output file.
{ -f | –file } file_format
use -hf for a complete list of supported file/data formats
–condensed-framing field_size_in_bits
specify storage size in bits for externally framed packet sizes.
Supported value is 16 for aac in m4a file format.

Other options:
{ -v | –verbose }
print progress verbosely
{ -t | –tag }
If encoding to CAF, store the source file’s format and name in a user
chunk. If decoding from CAF, use the destination format and filename
found in a user chunk.
{ –leaks }
run leaks at the end of the conversion
{ –profile }
collect and print performance information

Help options:
{ -hf | –help-formats }
print a list of supported file/data formats
{ -h | –help }
print this help


About alexkenis

Guitarist, philosopher, tinkerer

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: