1mod generated;
81mod name;
82#[cfg(feature = "serde")]
83mod serde;
84
85pub use generated::*;
91pub use name::ProgramName;
92
93use core::fmt;
94
95use crate::effect::{Algorithm, Engine};
96use crate::error::{Error, Result};
97use crate::ids::{PROGRAMS_PER_BANK, ProgramNumber, ProtocolVersion};
98use crate::param::{DEFAULT_FIRMWARE, PARAMETER_COUNT, ParamId};
99use crate::sysex::inquiry::Version;
100use crate::sysex::{Command, Message, PROGRAM_NAME_LEN, packed};
101
102#[derive(Clone, PartialEq, Eq, Hash)]
106pub struct Program {
107 version: ProtocolVersion,
108 data: [u8; Program::MAX_LEN],
109}
110
111impl Program {
112 pub const MAX_LEN: usize = ProtocolVersion::V7.program_data_len();
117
118 pub const PACKED_MAX_LEN: usize = packed::packed_len(Self::MAX_LEN);
120
121 #[must_use]
128 pub fn new(version: ProtocolVersion) -> Self {
129 let mut program = Self {
130 version,
131 data: [0; Self::MAX_LEN],
132 };
133 for parameter in ParamId::ALL.iter().copied() {
134 let min = u8::try_from(parameter.min()).unwrap_or(0);
135 program.set_clamped(parameter, min);
136 }
137 program
138 }
139
140 pub fn from_bytes(version: ProtocolVersion, bytes: &[u8]) -> Result<Self> {
151 let expected = version.program_data_len();
152 if bytes.len() != expected {
153 return Err(Error::ProgramLength {
154 expected,
155 found: bytes.len(),
156 });
157 }
158 let mut data = [0; Self::MAX_LEN];
159 for (slot, byte) in data.iter_mut().zip(bytes) {
160 *slot = *byte;
161 }
162 Ok(Self { version, data })
163 }
164
165 pub fn from_packed(version: ProtocolVersion, packed: &[u8]) -> Result<Self> {
179 let expected = version.program_data_len();
180 let found = packed::unpacked_len(packed.len())?;
181 if found < expected || found >= expected + packed::RAW_GROUP {
182 return Err(Error::ProgramLength { expected, found });
183 }
184 let mut scratch = [0; Self::MAX_LEN + packed::RAW_GROUP - 1];
186 packed::unpack_into(packed, &mut scratch)?;
187 let mut data = [0; Self::MAX_LEN];
188 for (slot, byte) in data.iter_mut().zip(scratch).take(expected) {
189 *slot = byte;
190 }
191 Ok(Self { version, data })
192 }
193
194 pub fn from_dump(message: &Message<'_>) -> Result<Self> {
204 match *message {
205 Message::ProgramDumpResponse {
206 version, packed, ..
207 }
208 | Message::EditBufferDumpResponse { version, packed } => {
209 Self::from_packed(version, packed)
210 }
211 other => Err(Error::NotAProgramDump(other.command().to_byte())),
212 }
213 }
214
215 #[must_use]
217 pub const fn version(&self) -> ProtocolVersion {
218 self.version
219 }
220
221 #[must_use]
223 pub fn as_bytes(&self) -> &[u8] {
224 self.data.get(..self.data_len()).unwrap_or(&self.data)
225 }
226
227 #[must_use]
233 pub fn reserved(&self) -> &[u8] {
234 self.as_bytes().get(PARAMETER_COUNT..).unwrap_or_default()
235 }
236
237 #[must_use]
239 pub fn packed_len(&self) -> usize {
240 packed::packed_len(self.data_len())
241 }
242
243 pub fn pack_into(&self, out: &mut [u8]) -> Result<usize> {
250 packed::pack_into(self.as_bytes(), out)
251 }
252
253 #[must_use]
255 pub fn get(&self, parameter: ParamId) -> u8 {
256 self.data
257 .get(usize::from(parameter.offset()))
258 .copied()
259 .unwrap_or(0)
260 }
261
262 #[must_use]
287 pub fn algorithm(&self, engine: Engine) -> Option<&'static Algorithm> {
288 self.algorithm_for(engine, DEFAULT_FIRMWARE)
289 }
290
291 #[must_use]
299 pub fn algorithm_for(&self, engine: Engine, firmware: Version) -> Option<&'static Algorithm> {
300 Algorithm::for_value(self.get(engine.algorithm_parameter()), firmware)
301 }
302
303 pub fn set(&mut self, parameter: ParamId, value: u8) -> Result<()> {
311 if !parameter.accepts(u16::from(value)) {
312 return Err(Error::ValueOutOfRange {
313 parameter: parameter.offset(),
314 value: u16::from(value),
315 max: parameter.max(),
316 });
317 }
318 self.write(parameter, value);
319 Ok(())
320 }
321
322 pub fn set_clamped(&mut self, parameter: ParamId, value: u8) -> u8 {
327 let clamped = u8::try_from(parameter.clamp(u16::from(value))).unwrap_or(value);
330 self.write(parameter, clamped);
331 clamped
332 }
333
334 pub fn values(&self) -> impl Iterator<Item = (ParamId, u8)> + '_ {
336 ParamId::ALL
337 .iter()
338 .copied()
339 .map(move |parameter| (parameter, self.get(parameter)))
340 }
341
342 pub fn changes<'a>(&'a self, target: &'a Self) -> impl Iterator<Item = (ParamId, u8)> + 'a {
361 ParamId::ALL.iter().copied().filter_map(move |parameter| {
362 let value = target.get(parameter);
363 (self.get(parameter) != value).then_some((parameter, value))
364 })
365 }
366
367 pub fn invalid(&self) -> impl Iterator<Item = (ParamId, u8)> + '_ {
372 self.values()
373 .filter(|(parameter, value)| !parameter.accepts(u16::from(*value)))
374 }
375
376 pub fn validate(&self) -> Result<()> {
383 match self.invalid().next() {
384 None => Ok(()),
385 Some((parameter, value)) => Err(Error::ValueOutOfRange {
386 parameter: parameter.offset(),
387 value: u16::from(value),
388 max: parameter.max(),
389 }),
390 }
391 }
392
393 #[must_use]
395 pub fn name(&self) -> ProgramName {
396 let start = usize::from(NAME_OFFSET);
397 ProgramName::from_field(
398 self.data
399 .get(start..start.saturating_add(NAME_LEN))
400 .unwrap_or_default(),
401 )
402 }
403
404 pub fn set_name(&mut self, name: ProgramName) {
409 let start = usize::from(NAME_OFFSET);
410 let field = self
411 .data
412 .get_mut(start..start.saturating_add(NAME_LEN))
413 .unwrap_or_default();
414 for (slot, byte) in field
415 .iter_mut()
416 .zip(name.as_bytes().iter().copied().chain(core::iter::repeat(0)))
417 {
418 *slot = byte;
419 }
420 }
421
422 #[must_use]
429 pub fn transpose(&self) -> i8 {
430 let raw = i16::from(self.get(ParamId::ProgramTranspose));
431 i8::try_from((raw - i16::from(transpose_centre())).clamp(-48, 48)).unwrap_or(0)
432 }
433
434 pub fn set_transpose(&mut self, semitones: i8) -> Result<()> {
440 let raw = i16::from(transpose_centre()) + i16::from(semitones);
441 let raw = u8::try_from(raw).unwrap_or(0);
442 self.set(ParamId::ProgramTranspose, raw)
443 }
444
445 fn data_len(&self) -> usize {
447 self.version.program_data_len()
448 }
449
450 fn write(&mut self, parameter: ParamId, value: u8) {
453 if let Some(slot) = self.data.get_mut(usize::from(parameter.offset())) {
454 *slot = value;
455 }
456 }
457}
458
459fn transpose_centre() -> u8 {
462 let parameter = ParamId::ProgramTranspose;
463 u8::try_from(parameter.min().midpoint(parameter.max())).unwrap_or(0)
464}
465
466impl fmt::Debug for Program {
467 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
469 f.debug_struct("Program")
470 .field("version", &self.version)
471 .field("name", &self.name())
472 .finish_non_exhaustive()
473 }
474}
475
476impl fmt::Display for Program {
477 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
478 fmt::Display::fmt(&self.name(), f)
479 }
480}
481
482#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
502pub struct BankNames<'a> {
503 unpacked: &'a [u8],
504}
505
506impl<'a> BankNames<'a> {
507 pub const COUNT: usize = PROGRAMS_PER_BANK as usize;
509
510 pub const LEN: usize = PROGRAM_NAME_LEN * Self::COUNT;
512
513 pub fn new(unpacked: &'a [u8]) -> Result<Self> {
520 if unpacked.len() != Self::LEN {
521 return Err(Error::PayloadLength {
522 command: Command::BankProgramNamesDumpResponse.to_byte(),
523 expected: Self::LEN,
524 found: unpacked.len(),
525 });
526 }
527 Ok(Self { unpacked })
528 }
529
530 #[must_use]
532 pub fn get(&self, program: ProgramNumber) -> ProgramName {
533 let start = usize::from(program.get()) * PROGRAM_NAME_LEN;
534 ProgramName::from_field(
535 self.unpacked
536 .get(start..start.saturating_add(PROGRAM_NAME_LEN))
537 .unwrap_or_default(),
538 )
539 }
540
541 pub fn iter(&self) -> impl Iterator<Item = ProgramName> + '_ {
543 self.unpacked
544 .chunks_exact(PROGRAM_NAME_LEN)
545 .map(ProgramName::from_field)
546 }
547}
548
549#[cfg(test)]
550#[expect(
551 clippy::expect_used,
552 reason = "a failed expectation is the test failure"
553)]
554mod tests {
555 use super::*;
556 use crate::ids::Bank;
557 use crate::param::Group;
558 use crate::sysex::inquiry::Version;
559
560 const FIRMWARE_1_0: Version = Version { major: 1, minor: 0 };
562
563 fn program() -> Program {
564 Program::new(ProtocolVersion::V6)
565 }
566
567 #[test]
570 fn the_name_is_the_parameters_at_the_offsets_the_field_occupies() {
571 assert_eq!(NAME_PARAMETERS.len(), NAME_LEN);
572 assert_eq!(
573 NAME_PARAMETERS.first().map(|parameter| parameter.offset()),
574 Some(NAME_OFFSET)
575 );
576 for (index, parameter) in NAME_PARAMETERS.iter().enumerate() {
577 let offset = NAME_OFFSET + u8::try_from(index).expect("seventeen fit in a byte");
578 assert_eq!(parameter.offset(), offset);
579 assert_eq!(parameter.group(), Group::Program);
580 }
581
582 assert_eq!(NAME_PARAMETERS.len(), ProgramName::MAX_CHARS + 1);
585 }
586
587 #[test]
590 fn naming_a_program_moves_only_the_characters_that_changed() {
591 let mut program = program();
592 program.set_name(ProgramName::new("Bass").expect("a name the display can write"));
593
594 let mut renamed = program.clone();
595 renamed.set_name(ProgramName::new("Bassy").expect("a name the display can write"));
596
597 assert!(
598 program
599 .changes(&renamed)
600 .eq([(ParamId::ProgramNameChar5, b'y')]),
601 "one character moved"
602 );
603 assert!(
604 program
605 .changes(&renamed)
606 .all(|(parameter, _)| NAME_PARAMETERS.contains(¶meter))
607 );
608 }
609
610 #[test]
611 fn a_dump_survives_the_round_trip_byte_for_byte() {
612 let mut bytes = [0; PARAMETER_COUNT];
613 for (offset, byte) in bytes.iter_mut().enumerate() {
614 *byte = u8::try_from(offset).unwrap_or(0).wrapping_mul(7);
616 }
617 let program = Program::from_bytes(ProtocolVersion::V6, &bytes).expect("a v6 program");
618 assert_eq!(program.as_bytes(), bytes);
619
620 let mut packed = [0; Program::PACKED_MAX_LEN];
621 let len = program.pack_into(&mut packed).expect("room to pack");
622 let read = Program::from_packed(ProtocolVersion::V6, packed.get(..len).expect("packed"))
623 .expect("a v6 program");
624 assert_eq!(read, program);
625 }
626
627 #[test]
630 fn padding_on_the_wire_is_not_part_of_the_program() {
631 let program = program();
632 assert_eq!(program.as_bytes().len(), 242);
633 assert_eq!(program.packed_len(), 280);
634
635 let mut packed = [0xFF; Program::PACKED_MAX_LEN];
636 let len = program.pack_into(&mut packed).expect("room to pack");
637 assert_eq!(len, 280);
638 let read = Program::from_packed(ProtocolVersion::V6, packed.get(..len).expect("packed"))
639 .expect("a v6 program");
640 assert_eq!(read, program);
641 }
642
643 #[test]
644 fn version_seven_keeps_its_reserved_bytes() {
645 let mut bytes = [0; 245];
646 for (index, byte) in bytes.iter_mut().enumerate().skip(PARAMETER_COUNT) {
647 *byte = u8::try_from(index).unwrap_or(0);
648 }
649 let seven = Program::from_bytes(ProtocolVersion::V7, &bytes).expect("a v7 program");
650 assert_eq!(seven.reserved(), &[242, 243, 244]);
651 assert_eq!(seven.as_bytes(), bytes);
652 assert!(program().reserved().is_empty());
653 }
654
655 #[test]
659 fn clamping_lands_inside_every_parameters_range() {
660 let mut program = program();
661 for parameter in ParamId::ALL.iter().copied() {
662 for value in 0..=u8::MAX {
663 let stored = program.set_clamped(parameter, value);
664 assert_eq!(program.get(parameter), stored);
665 assert!(
666 parameter.accepts(u16::from(stored)),
667 "{parameter} clamped {value} to {stored}"
668 );
669 }
670 }
671 }
672
673 #[test]
674 fn a_dump_of_the_wrong_length_is_refused() {
675 assert_eq!(
676 Program::from_bytes(ProtocolVersion::V6, &[0; 240]),
677 Err(Error::ProgramLength {
678 expected: 242,
679 found: 240,
680 })
681 );
682 }
683
684 #[test]
687 fn a_packed_run_may_carry_the_padding_of_its_last_group_and_no_more() {
688 let program = program();
689 let mut packed = [0; Program::PACKED_MAX_LEN + packed::PACKED_GROUP];
690 let len = program.pack_into(&mut packed).expect("room to pack");
691 assert_eq!(len, 280);
693 assert_eq!(
694 Program::from_packed(ProtocolVersion::V6, packed.get(..len).expect("in range")),
695 Ok(program.clone())
696 );
697 assert_eq!(
699 Program::from_packed(
700 ProtocolVersion::V6,
701 packed.get(..len + packed::PACKED_GROUP).expect("in range")
702 ),
703 Err(Error::ProgramLength {
704 expected: 242,
705 found: 252,
706 })
707 );
708 assert_eq!(
710 Program::from_packed(
711 ProtocolVersion::V6,
712 packed.get(..len - packed::PACKED_GROUP).expect("in range")
713 ),
714 Err(Error::ProgramLength {
715 expected: 242,
716 found: 238,
717 })
718 );
719 }
720
721 #[test]
722 fn transpose_is_clamped_to_the_range_the_manual_gives() {
723 let mut program = program();
724 program.set_clamped(ParamId::ProgramTranspose, 0);
725 assert_eq!(program.transpose(), -48);
726 program.set_clamped(ParamId::ProgramTranspose, 255);
727 assert_eq!(program.transpose(), 48);
728 }
729
730 #[test]
731 fn a_new_program_holds_what_every_parameter_accepts() {
732 let program = program();
733 assert_eq!(program.validate(), Ok(()));
734 assert_eq!(program.invalid().count(), 0);
735 assert_eq!(program.program_transpose(), 80);
737 assert_eq!(program.transpose(), -48);
738 }
739
740 #[test]
741 fn a_value_outside_the_range_is_kept_but_reported() {
742 let mut bytes = [0; PARAMETER_COUNT];
743 *bytes.get_mut(2).expect("offset 2") = 9;
745 let program = Program::from_bytes(ProtocolVersion::V6, &bytes).expect("a v6 program");
746
747 assert_eq!(program.get(ParamId::Lfo1Shape), 9);
748 assert_eq!(program.lfo1_shape(), None);
749 assert!(
750 program
751 .invalid()
752 .eq([(ParamId::Lfo1Shape, 9), (ParamId::ProgramTranspose, 0)]),
753 "both out-of-range bytes are reported, in offset order"
754 );
755 }
756
757 #[test]
758 fn setting_refuses_what_clamping_bends() {
759 let mut program = program();
760 assert_eq!(
761 program.set(ParamId::Lfo1Shape, 9),
762 Err(Error::ValueOutOfRange {
763 parameter: 2,
764 value: 9,
765 max: 6,
766 })
767 );
768 assert_eq!(program.set_clamped(ParamId::Lfo1Shape, 9), 6);
769 assert_eq!(program.lfo1_shape(), Some(LfoShape::SampleAndGlide));
770 }
771
772 #[test]
773 fn the_typed_accessors_are_the_bytes_under_another_name() {
774 let mut program = program();
775 program.set_lfo1_shape(LfoShape::Square);
776 program.set_lfo1_key_sync(true);
777 program.set_vcf_frequency(128);
778
779 assert_eq!(program.get(ParamId::Lfo1Shape), 2);
780 assert_eq!(program.get(ParamId::Lfo1KeySync), 1);
781 assert_eq!(program.get(ParamId::VcfFrequency), 128);
782 assert!(program.lfo1_key_sync());
783 assert_eq!(program.vcf_frequency(), 128);
784 }
785
786 #[test]
789 fn a_renumbered_table_reads_by_firmware() {
790 let mut program = program();
791 program.set_mod1_source(ModSource::Expression);
792 let raw = program.get(ParamId::Mod1Source);
793
794 assert_eq!(raw, 6);
795 assert_eq!(program.mod1_source(), Some(ModSource::Expression));
796 assert_eq!(
797 ModSource::from_raw_for(raw, FIRMWARE_1_0),
798 Some(ModSource::Lfo1)
799 );
800 assert_eq!(ModSource::Expression.raw_for(FIRMWARE_1_0), None);
801 assert_eq!(ModSource::Lfo1.raw_for(FIRMWARE_1_0), Some(6));
802 assert_eq!(ModSource::Expression.name(), "Expression");
803 assert_eq!(ModSource::Expression.name_for(FIRMWARE_1_0), None);
804 }
805
806 #[test]
807 fn every_value_of_every_table_survives_the_round_trip() {
808 for source in ModSource::ALL.iter().copied() {
809 assert_eq!(ModSource::from_raw(source.raw()), Some(source));
810 }
811 for destination in ModDestination::ALL.iter().copied() {
812 assert_eq!(
813 ModDestination::from_raw(destination.raw()),
814 Some(destination)
815 );
816 }
817 for effect in FxType::ALL.iter().copied() {
818 assert_eq!(FxType::from_raw(effect.raw()), Some(effect));
819 }
820 for shape in LfoShape::ALL.iter().copied() {
821 assert_eq!(LfoShape::from_raw(shape.raw()), Some(shape));
822 assert_eq!(
823 Some(shape.name()),
824 shape.name_for(crate::param::DEFAULT_FIRMWARE)
825 );
826 }
827 }
828
829 #[test]
830 fn a_name_is_written_and_read_back() {
831 let mut program = program();
832 program.set_name(ProgramName::new("Bass Sweep").expect("a valid name"));
833
834 assert_eq!(program.name().as_str(), "Bass Sweep");
835 assert_eq!(program.get(ParamId::ProgramNameChar1), b'B');
836 assert_eq!(program.get(ParamId::ProgramNameChar11), 0);
838 assert_eq!(program.get(ParamId::ProgramNameChar17), 0);
839
840 program.set_name(ProgramName::new("A").expect("a valid name"));
841 assert_eq!(program.name().as_str(), "A");
842 assert_eq!(program.get(ParamId::ProgramNameChar2), 0);
843 }
844
845 #[test]
846 fn transposition_counts_from_the_middle_of_its_range() {
847 let mut program = program();
848 program.set_transpose(0).expect("no transposition");
849 assert_eq!(program.program_transpose(), 128);
850 assert_eq!(program.transpose(), 0);
851
852 program.set_transpose(48).expect("four octaves up");
853 assert_eq!(program.program_transpose(), 176);
854 assert_eq!(program.transpose(), 48);
855
856 assert!(program.set_transpose(49).is_err());
857 assert!(program.set_transpose(-49).is_err());
858 }
859
860 #[test]
861 fn changes_are_the_edits_that_close_the_gap() {
862 let before = program();
863 let mut after = before.clone();
864 after.set_lfo1_rate(64);
865 after.set_lfo1_shape(LfoShape::Square);
866
867 assert!(
868 before
869 .changes(&after)
870 .eq([(ParamId::Lfo1Rate, 64), (ParamId::Lfo1Shape, 2)]),
871 "both edits are reported, in offset order"
872 );
873
874 let mut applied = before.clone();
875 for (parameter, value) in before.changes(&after) {
876 applied.set(parameter, value).expect("a value it accepts");
877 }
878 assert_eq!(applied, after);
879 assert_eq!(before.changes(&before).count(), 0);
880 }
881
882 #[test]
883 fn a_dump_message_carries_a_program_and_nothing_else_does() {
884 let program = program();
885 let mut packed = [0; Program::PACKED_MAX_LEN];
886 let len = program.pack_into(&mut packed).expect("room to pack");
887 let packed = packed.get(..len).expect("packed");
888
889 let dump = Message::EditBufferDumpResponse {
890 version: ProtocolVersion::V6,
891 packed,
892 };
893 assert_eq!(Program::from_dump(&dump), Ok(program.clone()));
894
895 let stored = Message::ProgramDumpResponse {
896 version: ProtocolVersion::V6,
897 bank: Bank::new(0).expect("bank A"),
898 program: ProgramNumber::new(0).expect("program 0"),
899 packed,
900 };
901 assert_eq!(Program::from_dump(&stored), Ok(program));
902
903 assert_eq!(
904 Program::from_dump(&Message::EditBufferDumpRequest),
905 Err(Error::NotAProgramDump(0x03))
906 );
907 }
908
909 #[test]
910 fn a_bank_of_names_is_read_where_it_lies() {
911 let mut unpacked = [0; BankNames::LEN];
912 let first = unpacked.get_mut(..4).expect("the first name");
913 first.copy_from_slice(b"Bass");
914 let second = unpacked
915 .get_mut(PROGRAM_NAME_LEN..PROGRAM_NAME_LEN + 16)
916 .expect("the second name");
917 second.copy_from_slice(b"SixteenCharacter");
918 let names = BankNames::new(&unpacked).expect("a bank of names");
919
920 assert_eq!(
921 names
922 .get(ProgramNumber::new(0).expect("program 0"))
923 .as_str(),
924 "Bass"
925 );
926 assert_eq!(
928 names
929 .get(ProgramNumber::new(1).expect("program 1"))
930 .as_str(),
931 "SixteenCharacter"
932 );
933 assert_eq!(names.iter().count(), 128);
934 assert_eq!(
935 BankNames::new(&[0; 16]),
936 Err(Error::PayloadLength {
937 command: Command::BankProgramNamesDumpResponse.to_byte(),
938 expected: BankNames::LEN,
939 found: 16,
940 })
941 );
942 }
943}