rework the track encoding details
add notes for low level api